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About CL Programming (SC41-5721) 


This book provides a wide-range discussion of OS/400 programming topics, 
including: 

* Control language programming. 

* OS/400 programming concepts. 

* Objects and libraries. 

* Message handling. 

* User-defined commands. 

* User-defined menus. 

* Testing functions. 


Who should read this book 


This book is intended for the OS/400 programmer or application programmer, 
including non-CL programmers. While CL Programming is discussed in detail, 
much of the material in this book applies to the system in general and may be 
used by programmers of all high-level languages supported by the iSeries servers. 


Prerequisite and related information 


Use the iSeries Information Center as your starting point for looking up iSeries 
technical information. 


You can access the Information Center two ways: 
* From the following Web site: 
http://www. ibm.com/eserver/iseries/infocenter 
* From CD-ROMs that ship with your Operating System/400 order: 


iSeries Information Center, SK3T-4091-02. This package also includes the PDF 
versions of iSeries manuals, iSeries Information Center: Supplemental Manuals, 
SK3T-4092-01, which replaces the Softcopy Library CD-ROM. 


The iSeries Information Center contains advisors and important topics such as 
Java, TCP/IP, Web serving, secured networks, logical partitions, clustering, CL 
commands, and system application programming interfaces (APIs). It also includes 
links to related IBM Redbooks and Internet links to other IBM Web sites such as 
the Technical Studio and the IBM home page. 


With every new hardware order, you receive the iSeries Setup and Operations 
CD-ROM, SK3T-4098-01. This CD-ROM contains IBM @server iSeries Access for 
Windows and the EZ-Setup wizard. iSeries Access offers a powerful set of client 
and server capabilities for connecting PCs to iSeries servers. The EZ-Setup wizard 
automates many of the iSeries setup tasks. 


For other related information, see the 


iSeries Navigator 


IBM iSeries Navigator is a powerful graphical interface for managing your iSeries 
servers. iSeries Navigator functionality includes system navigation, configuration, 
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planning capabilities, and online help to guide you through your tasks. iSeries 
Navigator makes operation and administration of the server easier and more 
productive and is the only user interface to the new, advanced features of the 
OS/400 operating system. It also includes Management Central for managing 
multiple servers from a central server. 


You can find more information on iSeries Navigator in the iSeries Information 
Center and at the following Web site: 


http://www. ibm.com/eserver/iseries/navigator/ 


How to send your comments 


Your feedback is important in helping to provide the most accurate and 
high-quality information. If you have any comments about this book or any other 
iSeries documentation, fill out the readers’ comment form at the back of this book. 


* If you prefer to send comments by mail, use the readers’ comment form with the 
address that is printed on the back. If you are mailing a readers’ comment form 
from a country other than the United States, you can give the form to the local 
IBM® branch office or IBM representative for postage-paid mailing. 


* If you prefer to send comments by FAX, use either of the following numbers: 
— United States, Canada, and Puerto Rico: 1-800-937-3430 
— Other countries: 1-507-253-5192 
* If you prefer to send comments electronically, use one of these e-mail addresses: 
— Comments on books: 
RCHCLERK@us.ibm.com 
— Comments on the iSeries Information Center: 
RCHINFOC@us.ibm.com 
Be sure to include the following: 
* The name of the book or iSeries Information Center topic. 
* The publication number of a book. 
* The page number or topic of a book to which your comment applies. 
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Chapter 1. Introduction 


This introduction describes several major concepts of Operating System /400* 
(OS/400*). These concepts are discussed in more detail in the following chapters. 


System operation is controlled by the following: 

* CL commands. CL commands are used singly in batch and interactive jobs, 
(such as from the Command Entry display) and in CL programs and procedures. 

* Menu options. System operation can be controlled by selecting menu options. 
Interactive users can use the iSeries server menus to perform many system tasks. 

* System messages. System messages are used to communicate between programs 
and procedures and to communicate between programs and procedures and 
users. Messages can report both status information and error conditions. 


Control Language 


Control language (CL) is the primary interface to the operating system and can be 
used at the same time by users at different work stations. A single control language 
statement is called a command. Commands can be entered in the following ways: 

* Individually from a work station. 

* As part of batch jobs. 


* As source statements to create a CL program or procedure. 


Commands can be entered individually from any command line or the Command 
Entry display. 


To simplify the use of CL, all the commands use a consistent syntax. In addition, 
the operating system provides prompting support for all commands, default values 
for most command parameters, and validity checking to ensure that a command is 
entered correctly before the function is performed. Thus, CL provides a single, 
flexible interface to many different system functions that can be used by different 
system users. 


Procedure 


A procedure is a set of self-contained high-level language statements that performs 
a particular task and then returns to the caller. 


In CL, a procedure usually begins with a PGM statement and ends with an 
ENDPGM statement. 


Module 


Module is the object that results from compiling source. A module must be bound 
into a program to run. 


A CL module consists of two parts: A user-written procedure, and a program entry 


procedure that is generated by the CL compiler. In other HLL (for example, C), a 
single module may contain multiple user-written procedures. 
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Program 


An ILE Program is an OS/400 object that combines one or more modules. Modules 
cannot be run until they are bound into programs. A program must have a 
program entry procedure. The CL compiler generates a program entry procedure 
in each module it creates. An OPM CL program is the object that results from 
compiling source using the CRTCLPGM command. 


Service Program 


Service program is an OS/400 object that combines one or more modules. You can 
run programs that are not bound to service programs if they do not require any 
procedures from the service program. However, you cannot run any procedures 
from a service program unless that service program is bound to a program. In 
order to call procedures in a service program, you must export the procedure 
name. 


While a program has only one entry point, a service program can have multiple 
entry points. You cannot call service programs directly. You can call procedures in 
a service program from other procedures in programs and service programs. 


Command Syntax 


A command name and parameters make up each command. A command name 
usually consists of a verb, or action, followed by a noun or phrase that identifies 
the receiver of the action. Abbreviated words, usually to three letters, make up the 
command name. This reduces the amount of typing that is required to enter the 
command. For example, one of the CL commands is the Send Message command. 
You would use the command that is named SNDMSG to send a message from a 
user to a message queue. 


The parameters used in CL commands are keyword parameters. The keyword, 
usually abbreviated the same way as commands, identifies the purpose of the 
parameter. However, when commands are entered, some keywords may be 
omitted by specifying the parameters in a certain order (positional specification). 


CL Procedures 


CL programs and procedures are made up of CL commands. The commands are 
compiled into an OPM program or a module that can be bound into programs 
made up of modules written in CL or other languages. Advantages of using CL 
programs and procedures include: 


* Using CL programs and procedures is faster than entering and running the 
commands individually. 

* CL programs and procedures provide consistent processing of the same set of 
commands and logic. 

* Some functions require CL commands that cannot be entered individually and 
must be part of a CL program or procedure. 

* CL programs and procedures can be tested and debugged like other high-level 
language (HLL) programs and procedures. 

* Parameters can be passed to CL programs and procedures to adapt the 
operations performed by the program or procedure to the particular 
requirements of that use. 

* You can bind CL modules with other ILE* high-level language modules into a 
program. 
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CL programs and procedures can be used for many kinds of applications. For 
example, CL procedures can be used to: 


* Provide an interface to the user of an interactive application through which the 
user can request application functions without an understanding of the 
commands used in the program or procedure. This makes the work station 
user’s job easier and reduces the chances of errors occurring when commands 
are entered. 


* Control the operation of an application by establishing variables used in the 
application (such as date, time, and external indicators) and specifying the 
library list used by the application. This ensures that these operations are 
performed whenever the application is run. 


* Provide predefined routines for the system operator, such as procedures to start 
a subsystem, to provide backup copies of files, or to perform other operating 
functions. The use of CL programs and procedures reduces the number of 
commands the operator uses regularly, and ensures that system operations are 
performed consistently. 


Most of the CL commands provided by the system can be used in CL programs 
and procedures. Some commands are specifically designed for use in CL programs 
and procedures and are not available when commands are entered individually. 
These commands include: 


* Logic control commands that can be used to control which operations are 
performed by the program or procedure according to conditions that exist when 
the program or procedure is run. For example, if a certain condition exists, then 
do certain processing, else do some other operation. These logic operations 
provide both conditional and unconditional branching within the CL program or 
procedure. 


* Data operations that provide a way for the program or procedure to 
communicate with a work station user. Data operations let the program or 
procedure send formatted data to and receive data from the work station, and 
allow limited access to the database. 


* Commands that allow the program or procedure to send messages to the display 
station user. 

* Commands that receive messages sent by other programs and procedures. These 
messages can provide normal communication between programs and 
procedures, or indicate that errors or other exceptional conditions exist. 

* The use of variables and parameters for passing information between commands 
in the program or procedure and between programs and procedures. 

* Calling other procedures (only programs can be called from the command line 
or in the batch job stream). 


Using CL programs and procedures, applications can be designed with a separate 
program or procedure for each function, and with a CL program or procedure 
controlling which programs or procedures are run within the application. The 
application can consist of both CL and other HLL programs or procedures. In this 
type of application, CL programs or procedures are used to: 


* Determine which programs or procedures in the application are to be run. 
* Provide system functions that are not available through other HLL languages. 
* Provide interaction with the application user. 


CL programs and procedures provide the flexibility needed to let the application 
user select what operations to perform and run the necessary procedures. 
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Command Definition 


Menus 


Command definition allows system users to create additional commands to meet 
specific application needs. These commands are similar to the system commands. 


Each command on the system has a command definition object and a command 

processing program (CPP). The command definition object defines the command, 

including: 

* The command name 

* The CrP 

* The parameters and values that are valid for the command 

* Validity checking information the system can use to validate the command when 
it is entered 

* Prompt text to be displayed if a prompt is requested for the command. 

* Online help information 


The CPP is the program called when the command is entered. Because the system 
performs validity checking when the command is entered, the CPP does not 
always have to check the parameters passed to it. 


The command definition functions can be used to: 


* Create unique commands needed by system users while keeping a consistent 
interface for CL command users. 


* Define alternative versions of CL commands to meet the requirements of system 
users. This function might include having different defaults for parameter 
values, or simplifying the commands so that some parameters would not need 
to be entered. Constant values can be defined for those parameters. The 
IBM*-supplied commands should not be changed. 


pte , for a detailed discussion of command 


definition. 


The system provides a large number of menus that allow users to perform many 
functions just by selecting menu options. The advantages of using menus to 
perform system tasks include: 


* Users do not need to understand CL commands and command syntax. 
* The amount of typing and the chance of errors are greatly reduced. 


Information about creating menus that can be used like the system-supplied menus 


is described in the |App 


Objects and Libraries 


An object is a named storage space that consists of a set of characteristics that 
describe itself and, in some cases, data. An object is anything that exists in and 
occupies space in storage and on which operations can be performed. The 
attributes of an object include its name, type, size, the date it was created, and a 
description provided by the user who created the object. The value of an object is 
the collection of information stored in the object. The value of a program, for 
example, is the code that makes up the program. The value of a file is the 
collection of records that makes up the file. The concept of an object simply 
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provides a term that can be used to refer to a number of different items that can be 
stored in the system, regardless of what the items are. 


Objects 


The functions performed by most of the CL commands are applied to objects. 
Some commands can be used on any type of object and others apply only to a 
specific type of object. 


The system supports various unique types of objects. Some types identify objects 
common to many data processing systems, such as: 

* Files 

* Programs 

* Commands 

* Libraries 

* Queues 

* Modules 

* Service programs 


Other object types are less familiar, such as: 
* User profiles 

* Job descriptions 

* Subsystem descriptions 

* Device descriptions 


Different object types have different operational characteristics. These differences 
make each object type unique. For example, because a file is an object that contains 
data, its operational characteristics differ from those of a program, which contains 
instructions. 


Each object has a name. The object name and the object type are used to identify 
an object. The object name is assigned by the user creating the object. The object 
type is determined by the command used to create the object. For example, if a 
program was created and given the name OEUPDT (for order entry update), the 
program could always be referred to by that name. The system uses the object 
name (OEUPDT) and object type (program) to locate the object and perform 
operations on it. Several objects can have the same name, but they must either be 
different object types or be stored in different libraries. 


The system maintains integrity by preventing the misuse of certain functions, 
depending on the object type. For example, the command CALL causes a program 
object to run. If you specified CALL and named a file, the command would fail 
unless there happened to be a program with the same name. 


Libraries 


A library is an object that is used to group related objects, and to find objects by 
name when they are used. Thus, a library is a directory to a group of objects. You 
can use libraries to group the objects into any meaningful collection. For example, 
you can group objects according to security requirements, backup requirements, or 
processing requirements. The amount of available storage limits the number of 
objects that a library can contain, and the number of libraries on the system. 
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The object grouping performed by libraries is a logical grouping. When a library is 
created, you can specify into which user auxiliary storage pool (ASP) the library 
should be created. All objects created into the library are created into the same ASP 
as the library. Objects in a library are not necessarily physically adjacent to each 
other. The size of a library, or of any other object, is not restricted by the amount of 
adjacent space available in storage. The system finds the necessary storage for 
objects as they are stored in the system. 


A library can be created into a basic user auxiliary storage pool (ASP) or an 
Independent Auxiliary Storage Pool. See the [independent ASPd article for details 
about the independent ASPs. 

* Objects can exist in libraries, libraries can exist in IASPs. 


* There can be more than one library with the same name in different [ASP 
groups. 


* Only one IASP group can be in the thread’s name space at a time. 
* An IASP group is added to the thread’s name space via SETASPGRP command. 


* A few commands allow the specification of an ASPDEV (CRTLIB DSPLIB 
DSPOBJD, eg) 


* Most commands require that the thread’s current ASP group be set to access 
libraries/ objects in the IASP. 


Most types of objects are placed in a library when they are created. The AUT 
parameter on CRTLIB defines the public authority of the library. The CRTAUT 
parameter specifies the default authority for objects that are created into the 
library. If the command creating the object specifies *LIBCRTAUT for the AUT 
parameter, the object’s public authority is the create authority that was specified 
for the library. You can move most object types from one library to another, but a 
single object cannot be in more than one library at the same time. When you move 
an object to a different library, the object is not moved in storage. You now locate 
the object through the new library. You can also rename and copy most object 
types from one library into another. 


A library name can be used to provide another level of identification to the name 
of an object. As described earlier, an object is identified by its name and its type. 
The name of the library further qualifies the object name. The combination of an 
object name and the library name is called the qualified name of the object. The 
qualified name tells the system the name of the object and the library it is in. 


The following diagram shows two libraries and the qualified names of the objects 
in them: 


Qualified 
Library: OELIB ObjectNames Library: PAYLIB 
ORDFIL OELIB/ORDFIL > EMPMAST 
r-——— OELIB/OEUPDT 
OEUPDT e+ f OELIB/CUSTMAST > PAYPGM 
PAYLIB/PAYPGM ——— 
PAYLIB/PAYHIST 
RBAFN548-0 
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Two objects with the same name and type can exist in different libraries. Two 
different objects with the same name cannot exist in the same library unless their 
object types differ. This design allows a program that refers to objects by name to 
work with different objects (objects with the same name but stored in different 
libraries) in successive runs of the program without changing the program itself. 
Also, a work station user who is creating a new object does not need to be 
concerned about names used for objects in other libraries. For example, in the 
following diagram, a new file named MONTHUPD (monthly update) could be 
added to the library OELIB, but not to the library ACCTLIB. The creation of the 
file into ACCTLIB would fail because another object named MONTHUPD and of 
type file already exists in library ACCTLIB. 


Library: OELIB Library: ACCTLIB 
ORDFIL OEUPDT ORDFIL BILLING 
(file) (program) (file) (program) 
CUSTMAST MONTHUPD 
(file) (file) 

A 
YES NO 
MONTHUPD 
(new file) 
RBAFN549-0 


An object is identified within a library by the object name and type. Many CL 
commands apply only to a single object type, so the object type does not have to 
be explicitly identified. For those commands that apply to many object types, the 
object type must be explicitly identified. 


1 for detail on how to use libraries to find objects. 


Messages 


A message is a communication sent from one user, program, or procedure to 
another. Most data processing systems provide communications between the 
system and the operator to handle errors and other conditions that occur during 
processing. OS/400 also provides message handling functions that support 
two-way communications between programs and system users, between programs, 
between procedures within a program, and between system users. Two types of 
messages are supported: 


* Immediate messages, which are created by the program or system user when 
they are sent and are not permanently stored in the system. 


* Predefined messages, which are created before they are used. These messages 
are placed in a message file when they are created, and retrieved from that file 
when they are used. 


Because messages can be used to provide communications between programs, 
between procedures in a program, and between programs and users, using the 
OS/400 message handling functions should be considered when developing 
applications. The following concepts of message handling are important to 
application development: 
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* Messages can be defined in messages files, which are outside the programs that 
use them, and variable information can be provided in the message text when a 
message is sent. Because messages are defined outside the programs, the 
programs do not have to be changed when the messages are changed. This 
approach also allows the same program to be used with message files containing 
translations of the messages into different languages. 


* Messages are sent to and received from message queues, which are separate 
objects on the system. A message sent to a queue can remain on the queue until 
it is explicitly received by a program or work station user. 

* A program can send messages to a user who requested the program regardless 
of what work station that user has signed on to. Messages do not have to be 
sent to a specific device; one program can be used from different work stations 
without change. 


See the Globalization topic in the System overview, planning, and installation 
category of the iSeries Information Center for information on Coded Character Set 
Identifier (CCSID) for menus, messages, and message descriptions. 


Message Descriptions 


A message description defines a message to OS/400. The message description 
contains the text of the message and information about replacement variables, and 
can include variable data that is provided by the message sender when the 
message is sent. 


Message descriptions are stored in message files. Each description must have an 
identifier that is unique within the file. When a message is sent, the message file 
and the message identifier tell the system which message description is to be used. 


Message Queues 


When a message is sent to a procedure, a program, or a system user, it is placed 
on a message queue associated with that procedure, program, or user. The 
procedure, program, or user sees the message by receiving it from the queue. 


OS/400 provides message queues for: 
* Each work station on the system 

* Each user enrolled on the system 

* The system operator 

* The system history log 


Additional message queues can be created to meet any special application 
requirements. Messages sent to message queues are kept, so the receiver of the 
message does not need to process the message immediately. 


Testing Functions 


The system includes functions that let a programmer observe operations performed 
as a program runs. These functions can be used to locate operations that are not 
performing as intended. Testing functions can be used in either batch or interactive 
jobs from a work station. In either case, the program being observed must be in 
the testing environment, called debug mode. 


The testing functions narrow the search for errors that are difficult to find in the 
procedure’s source statements. Often, an error is apparent only because the output 


8 0S/400 CL Programming V5R2 


produced is not what is expected. To find those errors, you need to be able to stop 
the program at a given point (called a breakpoint) and examine variable information 
in the program to see if it is correct. You might want to make changes to those 
variables before letting the program continue running. 


You do not need to know machine language instructions, nor is there a need to 
include special instructions in the program to use the testing functions. The 
OS/400 testing functions lets you: 


* Stop a running program at any named point in the program’s source statements. 


* Display information about procedure variables at any point where the program 
can be stopped. You can also change the variable information before continuing 
procedure processing. 


See the appropriate ILE guide for debugging information with other ILE 
languages. 
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Chapter 2. CL Programming 


The focus of this chapter is ILE rather than OPM. For this reason, ‘procedure’ is 
used rather than ‘program’ for this chapter. However, when the discussion is about 
CL commands in general, the word ‘program’ may still be used. 


A CL procedure is a group of CL commands that tells the system where to get 
input, how to process it, and where to place the results. The procedure is assigned 
a name by which it can then be called by other procedures or bound into a 
program and called. As with other kinds of procedures, you must enter CL 
procedure source statements, compile, and bind them before you can run the 
procedure. 


When you enter CL commands individually (from the Command Entry display, for 
instance, or as individual commands in an input stream), each command is 
separately processed. When you enter CL commands as source statements for a CL 
procedure, the source remains for later modification if you choose, and the 
commands are compiled into a module. This module remains as a permanent 
system object that can be bound into other programs and run. Thus, CL is actually 
a high-level programming language for system functions. CL procedures ensure 
consistent processing of groups of commands. You can perform functions with a 
CL procedure that you cannot perform by entering commands individually, and 
the CL program or procedure provides better performance at run time than the 
processing of several separate commands. 


CL procedures can be used in batch or interactive processing. Certain commands 
or functions are restricted to either batch or interactive jobs. 


CL source statements consist of CL commands. You cannot use all CL commands 
as CL source statements, and you can use some of them only in CL procedures or 
OPM programs. You can determine what restrictions you want placed on the use 
of CL commands. You can do this by checking the box in the upper right-hand 
corner of the syntax diagram of a command. An example that uses the Program 
(PGM) command is shown below: 


Pgm: BI 


(2) 


>< 


>>—PGM 


(1) | 
__PARM(—*-&CL-variable-name |) 


Notes: 
1 A maximum of 40 repetitions. 


2 All parameters preceding this point can be specified positionally. 


You can find the syntax diagrams in the CL section of the Programming category in 
the iSeries Information Center. 
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The Pgm: B,I in the syntax diagram for the PGM command shows that this 
command can be used in either batch or interactive jobs, but can be used only 
within a CL program or procedure. 


The commands that you can use only as source statements in CL programs and 
procedures will have Pgm: in the box. If the box does not contain this indicator, 
you cannot use the command as source for a CL program or procedure. IBM has 
online information about how to read a syntax diagram. Refer to the CL section of 
the Programming category in the iSeries Information Center. 


CL source statements can be entered in a database source member either 
interactively from a work station or in a batch job input stream from a device. To 
create a program using CL source statements, you must enter the source statements 
into a database source member. You can then create an ILE program by compiling 
the source member into a module and binding the module into a program object. 


CL procedures can be written for many purposes, including: 


* To control the sequence of processing and calling of other programs or 
procedures. 


* To display a menu and run commands based on options selected from that 
menu. This makes the work station user’s job easier and reduces errors. 


¢ To read a database file. 


* To handle error conditions issued from commands, programs or procedures, by 
monitoring for specific messages. 


* To control the operation of an application by establishing variables used in the 
application, such as date, time, and external indicators. 


* To provide predefined functions for the system operator, such as starting a 
subsystem or saving files. This reduces the number of commands the operator 
uses regularly, and it ensures that system operations are performed consistently. 


There are many advantages in using CL procedures for an application. For 
example: 


* Because the commands are stored in a form that can be processed when the 
program is created, using programs is faster than entering and running the 
commands individually. 


* CL procedures are flexible. Parameters can be passed to CL procedures to adapt 
the operations performed by the procedure to the requirements of a particular 
use. 


* CL procedures can be tested and debugged like other high-level language 
programs and procedures. 


* CL procedures and programs can incorporate conditional logic and special 
functions not available when commands are entered individually. 


* CL procedures can be bound with procedures of other languages. 


You cannot use CL procedures to: 

* Add or update records in database files. 
* Use printer or ICF files. 

* Use subfiles within display files. 

* Use program-described display files. 


12 0S/400 CL Programming V5R2 


Creating a CL Program 


All programs are created in steps: 


1. Source creation. CL procedures consist of CL commands. In most cases, source 
statements are entered into a database file in the logical sequence determined 
by your application design. 


2. Module creation. Using the Create Control Language Module (CRTCLMOD) 
command, this source is used to create a system object. The created CL module 
can be bound into programs. A CL module contains one CL procedure. Other 
HLL languages may contain multiple procedures for each module. 


3. Program creation. Using the Create Program (CRTPGM) command, this module 
(along with other modules and service programs) is used to create a program. 


Note: If you want to create a program consisting of only one CL module, you can 
use the Create Bound CL Program (CRTBNDCL) command, which combines 
steps 2 and 3. 


Interactive Entry 


The iSeries server provides many menus and displays to assist the programmer, 
including the Programmer Menu, the Command Entry display, command prompt 
displays, and the Programming Development Manager (PDM) Menu. If your 


server uses the security functions described in Eecuibcs Referoncd , your 


ability to use these displays is controlled by the authority given to you in your 
user profile. User profiles are generally created and maintained by a system 
security officer. 


The most frequently used source entry method is the source entry utility (SEU), 
which is part of the WebSphere Development Studio. 


Batch Entry 


You can create CL source, a CL module, and a program in one batch input stream 
from diskette. The following example shows the basic parts of the input stream 
from a diskette unit. The input is submitted to a job queue using the Submit 
Diskette Job (SBMDKTJOB) command. The input stream should follow this format: 
// BCHJOB 


CRTBNDCL PGM(QGPL/EDUPGM) SRCFILE(PERLIST) 
// DATA FILE(PERLIST) FILETYPE(*SRC) 


(CL Procedure Source) 
// 


/* 
// ENDINP 


This stream creates a program from inline source. If you want to keep the source 
inline, a Copy File (CPYF) command could be used to copy the source into a 
database file. The program could then be created using the database file. 


You can also create a CL module directly from CL source on external media, such 
as diskette, using an IBM-supplied device file. The IBM-supplied diskette source 
file is QDKTSRC (use QTAPSRC for tape). Assume, for instance, that the CL source 
statements are in a source file on diskette named PGMA. 
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The first step is to identify the location of the source on diskette by using the 
following override command with LABEL attribute override: 


OVRDKTF FILE(QDKTSRC) LABEL(PGMA) 


Now you can consider the QDKTSRC file as the source file on the Create CL 
Module (CRTCLMOD) command. To create the CL module based on the source 
input from the diskette, enter the following command: 


CRTCLMOD MODULE(QGPL/PGMA) SRCFILE(QDKTSRC) 


When the CRTCLMOD command is processed, it treats the QDKTSRC source file 
like any database source file. Using the override, the source is located on diskette. 
PGMA is created in QGPL, and the source for that module remains on diskette. 


Parts of a CL Procedure 


While each source statement entered as part of a CL procedure is actually a CL 
command, the source can be divided into the following basic parts used in many 
typical CL procedures. 


PGM command 
PGM PARM(8&A) 


Optional PGM command beginning the procedure and identifying any 
parameters received. 


Declare commands 
(DCL, DCLF) 


Mandatory declaration of procedure variables when variables are used. The 
declare commands must precede all other commands except the PGM 
command. 


CL processing commands 
CHGVAR, SNDPGMMSG, OVRDBF, DLTF, ... 


CL commands used as source statements to manipulate constants or 
variables (this is a partial list). 


Logic control commands 
IF, THEN, ELSE, DO, ENDDO, GOTO 


Commands used to control processing within the CL procedure. 


Built-in functions 
%SUBSTRING (%SST), %SWITCH, and %BINARY (%BIN) 


Built-in functions and operators used in arithmetic, relational or logical 
expressions. 


Program control commands 
CALL, RETURN 


CL commands used to pass control to other programs. 


Procedure control commands 
CALLPRC, RETURN 


CL commands used to pass control to other procedures. 


ENDPGM command 
ENDPGM 


Optional End Program command. 
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The sequence, combination, and extent of these components are determined by the 
logic and design of your application. 


ACL procedure may refer to other objects that must exist when the procedure is 
created, when the command is processed, or both. This distinction is discussed in 

g era ag 1, and in the sections discussing 
various objects. In some circumstances, for your procedure to run successfully, you 
may need: 


Accessing Obie D ocram on page 14 


* A display file. Use display files to format information on a device display. If 
your procedure uses a display, you must enter and create the display file and 
record format by using the Create Display File (CRTDSPF) command before 
creating the module. You must declare it to the procedure in the DCL section by 
cae eee eGecie es eed 

for more information. 

* A database file. Records in a database file may be read by a CL procedure. If 
your procedure uses a database file, the file must be created using the Create 
Physical File (CRTPF) command or the Create Logical File (CRTLF) command 
before the module is created. You can use Data Description Specifications (DDS), 
Structured Query Language (SQL), or interactive data definition utility (IDDU) 
to define the format of the records in the file. The file must also be declared to 
the procedure in the DCL section using the Declare File (DCLF) command. See 


* Other programs. If you use a CALL command, the called program must exist 
before running the CALL command. It does not have to exist when compiling 


the calling module. See 
Chanter 4 for more information. 


* Other procedures. If you use the CALLPRC command, the called procedure 
must exist at the time CRTPGM is run. It does not have to exist when 
CRTCLMOD is run. 


Example of a Simple CL Program 


ACL program can be as simple or as complex as you want. To consolidate several 

activities normally done by the system operator at the beginning of the day (to call 
programs A, B, and C, for example), you can create a CL procedure STARTUP with 
the following code: 

PGM /* STARTUP */ 

CALL PGM(A) 

CALL PGM(B) 

CALL PGM(C) 

ENDPGM 


In this example, the Programmer Menu is used to create the program. You could 


also use the programming development manager (PDM), which is part of the 
WebSphere Development Studio. 
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To enter, create, and use this program, follow these steps: 


Enter CL Source Display Physical File Member 
Interactively enter CL Option 8 0001.00 PGM /*STARTUP*/ 
source in a physical Programmer |———»} 0002.00 CALLPGM(A) 
file member, using the Menu 0003.00 CALLPGM(B) 
source entry ulitity 0004.00 CALLPGM(C) 
(SEU). 0005.00 ENDPGM 
Create Program Display STARTUP 
Create a program Option 3 Object 
object from the source Programmer }—______»_ after <— 
using the CRTBNDCL Menu Creation 
command. 
Run Program Display 
Call the program Option 4 
using a CALL Programmer 
command. Menu 

RBAFN529-0 


To enter CL source: 


* Select option 8 (Edit source) on the Programmer Menu and specify STARTUP in 
the Parm field. (This option creates a source member named STARTUP that will 
also be the name of the program.) 

* Specify CLLE in the Type field and press the Enter key. 


* On the SEU display, use the I (insert) line command to enter the CL commands 
(CALL is a CL command). 


i 
COLUMNS « c:c.6 ees 8 1 71 Edit QGPL/QCLSRC 
Bandi eed cst STARTUP 
FMT Ax ..... Ri Re ree ee eenwisiadtney cre OMe ateretiarcte a Gubsperestisserome Oy ese cthtstie: "Oucsrsvasti ves nUrs 
KREKEKKEKKREKEKRE Beginning OF data KRKKKKKKKKKKKEK EK EKER KKRERKEKEKERERERE 
Ss y/ 


When you have finished entering the source statements: 
* Press F3 to exit from SEU. 


* Accept the default on the exit display (option 2, Exit and update member) and 
press the Enter key to return to the Programmer Menu. 


* Select option 3 (Create object) to create a program from the source statements 
you entered. You do not have to change any other information on the display. 


Note: The referenced programs (A, B, and C) do not have to exist when the 
program STARTUP is created. 


When the program is created, you can call it from the Programmer Menu by 
selecting option 4 (Call program) and specifying STARTUP in the Parm field. If 


16 05/400 CL Programming V5R2 


you attempt to run this sample program, however, the referenced programs must 
exist by the time the CALL commands are run. 


Commands Used in CL Procedures 


A CL procedure can contain only CL commands. These can be IBM-supplied or 
commands defined by you. You cannot use some IBM-supplied commands in CL 
procedures. IBM has online information concerning the individual command 
descriptions and their applicability in CL procedures. Refer to the CL section of the 
Programming category in the iSeries Information Center. 


Commands Entered on the RQSDTA and CMD Parameters 


Certain CL commands, such as Transfer Job (TFRJOB) and Submit Job (GSBMJOB) 
have ROSDTA or CMD parameters that can use another CL command as the 
parameter value. Commands that can only be used within CL procedures cannot 
be used as values on the ROSDTA or CMD parameter. 


CL Commands 


The following is a list of commands that are frequently used in CL procedures. You 
can use this list to select the appropriate command for the function you want. IBM 
provides online information on how to determine the command you might need. 
Refer to the CL section of the Programming category in the iSeries Information 
Center for this information. Familiarity with the function of these commands will 
help you to understand subsequent topics in this chapter. Superscript 1 indicates 
the commands that you can use only in CL programs and procedures. 


System Function 


Change Procedure 
Control 


CL Procedure 
Limits 


CL Procedure 
Logic 


CL Procedure 
Variables 


Conversion 


Data Areas 


Files 


Command 


CALL (Call) 


CALLPRC (Call Procedure) ! 
RETURN (Return) 


PGM (Program) ! 


ENDPGM (End Program) ' 
IF (If) ? 


ELSE (Else) * 


DO (Do) * 

ENDDO (End Do) ! 

GOTO (Go To) ? 

CHGVAR (Change Variable)! 


DCL (Declare) ! 

CHGVAR (Change Variable)! 
CVTDAT (Convert Date) ! 
CHGDTAARA (Change Data Area) 
CRTIDTAARA (Create Data Area) 
DLTDTAARA (Delete Data Area) 
DSPDTAARA (Display Data Area) 
RTVDTAARA (Retrieve Data Area) * 
ENDRCYV (End Receive) * 


DCLF (Declare File) ' 


Command Function 


Calls a program 


Calls a procedure. 

Returns to the command following the command that 
caused a program or procedure to be run 

Indicates the start of CL procedure source 


Indicates the end of CL procedure source 

Processes commands based on the value of a logical 
expression 

Defines the action to be taken for the else (false) 
condition of an IF command 

Indicates the start of a Do group 

Indicates the end of a Do group 

Branches to another command 

Changes the value of a CL variable 


Declares a variable 

Changes the value of a CL variable 

Changes the format of a date 

Changes a data area 

Creates a data area 

Deletes a data area 

Displays a data area 

Copies the content of a data area to a CL variable 
Cancels a request for input previously issued by a 
RCVF, SNDF, or SNDRCVF command to a display file 
Declares a display or database file 
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Command 


RCVF (Receive File) ' 
RTVMBRD (Retrieve Member 
Description) * 

SNDF (Send File) ' 

SNDRCVF (Send/Receive File) * 


System Function 


WAIT (Wait) ! 
Messages MONMSG (Monitor Message) ' 
RCVMSG (Receive Message) ! 
RMVMSG (Remove Message) ! 
RTVMSG (Retrieve Message) ' 
SNDPGMMSG (Send Program 
Message) ! 

SNDRPY (Send Reply) ' 
SNDUSRMSG (Send User Message) 


Miscellaneous 
Commands 


CHKOBJ (Check Object) 


PRTCMDUSG (Print Command 
Usage) 


RTVCFGSRC (Retrieve Configuration 
Source) 


RTVCFGSTS (Retrieve Configuration 
Status) ¢ 


RTVJOBA (Retrieve Job Attributes) ! 
RTVSYSVAL (Retrieve System Value) 
1 

RTVUSRPRE (Retrieve User Profile) * 


Program Creation 
Commands 


CRTCLMOD (Create CL Module) 


DLTMOD (Delete Module) 
DLTPGM (Delete Program) 
CRTBNDCL (Create Bound Control 
Language Program) 

CRTCLPGM (Create CL Program) 
CRTPGM (Create Program) 
CRTSRVPGM (Create Service 
Program) 


Command Function 


Reads a record from a display or database file 
Retrieves a description of a specific member of a 
database file 

Writes a record to a display file 

Writes a record to a display file and reads that record 
after the user has replied 

Waits for data to be received from an SNDF, RCVF, or 
SNDRCVF command issued to a display file 

Monitors for escape, status, and notify messages sent to 
a program’s message queue 

Copies a message from a message queue into CL 
variables in a CL procedure 

Removes a specified message from a specified message 
queue 

Copies a predefined message from a message file into 
CL procedure variables 

Sends a program message to a message queue 


Sends a reply message to the sender of an inquiry 
message 

Sends an informational or inquiry message to a display 
station or system operator 

Checks for the existence of an object and, optionally, the 
necessary authority to use the object 

Produces a cross-reference listing for a specified group 
of commands used in a specified group of CL 
procedures 

Generates CL command source for creating existing 
configuration objects and places the source in a source 
file member 

Gives applications the capability to retrieve 
configuration status from three configuration objects: 
line, controller, and device. 

Retrieves the value of one or more job attributes and 
places the values in a CL variable 

Retrieves a system value and places it into a CL variable 


Retrieves user profile attributes and places them into CL 
variables 
Creates a CL module 


Deletes a module 
Deletes a program 
Creates a bound CL program. 


Creates an OPM CL program. 
Creates a program from one or more modules. 
Creates a service program from one or more modules. 


Using CL Procedures 


CL programming is a flexible tool allowing you to perform a variety of operations. 
Each of the following uses is described in greater detail in individual sections later 
in this chapter. In general, you can: 
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* Use variables, logic control commands, expressions, and built-in functions to 
manipulate and process data within a CL procedure: 


PGM 

DCL &C *LGL 

DCL &A *DEC VALUE(22) 

DCL &B *CHAR VALUE(ABCDE) 


CHGVAR &A (&A + 30) 


IF (&A < 50) THEN(CHGVAR &C '1') 


DSPLIB ('Q' || &B) 


IF (%SST(&B 5 1)=E) THEN(CHGVAR &A 12) 


ENDPGM 
* Use a system value as a variable in a CL procedure. 


PGM 
DCL &TIME *CHAR 6 


SystemValues 


QTIME >RTVSYSVAL QTIME &TIME 
QDATE 


ENDPGM 
RBAFN551-0 


* Use a job attribute as a variable in a CL procedure. 


PGM 
DCL &USER *CHAR 10 


Job Attributes 


Job Name 7 
User Name ————————_® RTVJOBA USER(&USER) 
Job Number 


ENDPGM 


RBAFN552-0 
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* Send and receive data to and from a display file with a CL procedure. 


Data Description 
Specifications 


(DDS) 


Display 


Option _ 


PGM 
DCL FILE(DISPLAY) 
DCL &OPTION *CHAR 2 


RCVF... 


>IF (&OPTION*EQ1) THEN(CALLPGMA) 


ENDPGM 
RBAFN553-0 


* Create a CL procedure to monitor error messages for a job, and take corrective 


action if necessary. 
PGM 


MONMSG MSGID(CPF0001) EXEC(GOTO ERROR) 


CALL PROGA 
CALL PROGB 
RETURN 


ERROR: SNDPGMMSG MSG('A CALL command failed') MSGTYPE(*ESCAPE) 


ENDPGM 


* Control processing among procedures and programs and pass parameters from a 
CL procedure to other procedures or programs to override files. 
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PROCA PROCB 


PGM r——> PGM 
DCL... DCL... 
CALL PROCB 


CALL PROCC PARM(&FILEX) 


ENDPGM 


RETURN 
ENDPGM 


PROCC 


~~» PGM (&FILEX) 
DCL... 


OVRDBF FILE(INPUT) TOFILE(&FILEX) 


CALLPROCD > 


RETURN 
ENDPGM 
RBAFN554-0 


Used as a controlling procedure, a CL procedure can call procedures written in 
other languages. The following illustration shows how control can be passed 
between a CL procedure and RPG IV* and ILE COBOL procedures in an 
application. To use the application, a work station user would request program A, 
which controls the entire application. The illustration shows: The preceding 
example shows a single bound program (PGMA) that is called using the CALL 
command with PGMA. PGMA consists of: 


* ACL procedure (PGMA) calling an RPG IV procedure (PGMB) 

* An RPG IV procedure (PGMB) calling another RPG IV procedure (PGMC) 
¢ An RPG IV procedure (PGMB) calling a CL procedure (PGMD) 

* ACL procedure (PGMA) calling an ILE COBOL procedure (PGME) 

* An ILE COBOL program (PGME) calling a CL procedure (PGMF) 
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Start 


PGMA (CL) —»PGMB (RPG) PGMC (RPG) 
CALLPRC PGMB+— . 
gS SCALLB PGMC + : 
a END 
CALLPRC PGME-— —+pcMD (CL) 
ENDPGM CALLB PGMD 
a RETURN 
‘> PGME (COBOL) Rev 
—»PGMF (CL) 
CALL PGMF 
. 4+ __}+_ . 
RETURN 
EXIT PROGRAM RBAFN502-0 


The procedures can be created as indicated in the following example. You can enter 
source for procedures in separate source members. 


CRTCLMOD PGMA 

CRTRPGMOD PGMB 

CRTRPGMOD PGMC 

CRTCLMOD PGMD 

CRTCBLMOD PGME 

CRTCLMOD PGMF 

CRTPGM PGM(PGMA) + 
MODULE(PGMA PGMB PGMC PGMD PGME PGMF) + 
ENTMOD (*FIRST) 


Working with Variables 


CL procedures consist of CL commands, and the commands themselves consist of 
the command statement, parameters, and parameter values. IBM provides online 
information that explains the syntax rules for writing commands. Refer to the CL 
section of the Programming category in the iSeries Information Center for the 
explanation. 


Parameter values may be expressed as variables, constants, or expressions. A 
variable is a named changeable value that can be accessed or changed by referring 
to its name. Variables can be used as substitutes for most parameter values on CL 
commands. When a CL variable is specified as a parameter value and the 
command containing it is run, the value of the variable is used as the parameter 
value. Every time the command is run, a different value can be substituted for the 
variable. Variables and expressions can be used as parameter values only in CL 
procedures and programs. 


Variables are not stored in libraries; they are not objects; and their values are 
destroyed when the procedure that contains them is no longer active. The use of 
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variables as values gives CL programming a special flexibility, because this allows 
high-level manipulation of objects whose content may change by specific 
applications. You might, for instance, write a CL procedure to direct the processing 
of other programs or the operation of several work stations without specifying 
which programs or work stations are to be controlled. The system identifies these 
as variables in the CL procedure. You can define (specify) the value of the variables 
when running the CL procedure. 


All variables must be declared (defined) to the CL procedure before they can be 
used by the procedure: 


* Declare variable. Defining it is accomplished using the Declare CL Variable 
(DCL) command and consists of defining the attributes of the variable. The 
attributes are type, length, and initial value. 

DCL VAR(&AREA) TYPE(*CHAR) LEN(4) VALUE(BOOK) 


* Declare file. If your CL procedure uses a file, you must specify the name of the 
file in the FILE parameter on the Declare File (DCLF) command. The file 
contains a description (format) of the records in the file and the fields in the 
records. During compilation, the DCLF command implicitly declares CL 
variables for the fields and indicators defined in the file. 


For example, if the DDS for the file has one record in it with two fields (Fl and 
F2), then two variables, &F1 and &F2, are automatically declared in the 
program. 


DCLF FILE(MCGANN/GUIDE) 


If the file is a physical file which was created without DDS, one variable is 
declared for the entire record. The variable has the same name as the file, and its 
length is the same as the record length of the file. 


The declare commands must precede all other commands in the procedure (except 
the PGM command), but they can be intermixed in any order. 


In addition to the uses discussed in this section, variables can be used to: 


* Pass information between procedures and jobs. See (Chapter 3. “Controlling Flow 


* Pass information between procedures and device displays. See 


M ple De 


Conditionall ‘Controlling Processing within a 


* Create objects. A variable can be used in place of an object name or library 
name, or both. The following example shows the Create Physical File (CRTPF) 
command used with a specified library in the first line, and with a variable 
replacing the library name in the second line: 


CRTPF FILE(DSTPRODLB/&FILE) 
CRTPF FILE(&LIB/&FILE) 


Variables cannot be used to change a command name or keyword or to specify a 
procedure name for the CALLPRC command. Command parameters, however, can 
be changed during the processing of a CL procedure through the use of the 


rompting function. See “A g ane 
for more information. 
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It is also possible to assemble the keywords and parameters for a command and 


Declaring a Variable 


In its simplest form, the Declare CL Variable (DCL) command has the following 
parameters: 


*CHAR 
DCL VAR(variable-name) TYPE *DEC LEN(length) 
VALUE(initial-value) *LGL 


RVv2W271-1 


When you use a DCL command, you must use the following rules: 


* The CL variable name must begin with an ampersand (&) followed by as many 
as 10 characters. The first character following the & must be alphabetic and the 
remaining characters alphanumeric. For example, &PART 


* The CL variable value must be one of the following: 
— Acharacter string as long as 5000 characters. 


— A packed decimal value totaling up to 15 digits with as many as 9 decimal 
positions. 


— A logical value ’0’ or ‘1’, where ’0’ can mean off, false, or no, and ‘1’ can 
mean on, true, or yes. A logical variable must be either ’0’ or ‘1’. 


* If you do not specify an initial value, the following is assumed: 
— 0 for decimal variables 
— Blanks for character variables 
— ‘0’ for logical variables. 


For decimal and character types, if you specify an initial value and do not 
specify the LEN parameter, the default length is the same as the length of the 
initial value. For type *CHAR, if you do not specify the LEN parameter, the 
string can be as long as 5000. 


* Declare the parameters as variables in the program DCL statements. 


Using Variables to Specify a List or Qualified Name 
The value on a parameter may be a list. For example, the Change Library List 
(CHGLIBL) command requires a list of libraries on the LIBL parameter, each 
separated by blanks. The elements in this list can be variables: 
CHGLIBL LIBL(&LIB1 &LIB2 &LIB3) 


When variables are used to specify elements in a list, each element must be 
declared separately: 


DCL VAR(&LIB1) TYPE(*CHAR) LEN(10) VALUE (QTEMP) 
DCL VAR(&LIB2) TYPE(*CHAR) LEN(10) VALUE(QGPL) 
DCL VAR(&LIB3) TYPE(*CHAR) LEN(10) VALUE(DISTLIB) 
CHGLIBL LIBL(&LIB1 &LIB2 &LIB3) 


Variable elements cannot be specified in a list as a character string: 


Incorrect: 
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DCL VAR(&LIBS) TYPE(*CHAR) LEN(20) + 
VALUE('QTEMP QGPL DISTLIB') 
CHGLIBL LIBL(&LIBS) 


When presented as a single character string, the system does not view the list as a 
list of separate elements, and an error will occur. 


You can also use variables to specify a qualified name, if each qualifier is declared 
as a separate variable: 

DCL VAR(&PGM) TYPE(*CHAR) LEN(10) 

DCL VAR(&LIB) TYPE(*CHAR) LEN(10) 

CHGVAR VAR(&PGM) VALUE (MYPGM) 

CHGVAR VAR(&LIB) VALUE (MYLIB) 


DLTPGM PGM(&LIB/&PGM) 
ENDPGM 


In this example, the program and library name are declared separately. The 
program and library name cannot be specified in one variable, as in the following 
example: 


Incorrect: 


DCL VAR(&PGM) TYPE(*CHAR) LEN(11) 
CHGVAR VAR(&PGM) VALUE('MYLIB/MYPGM' ) 
DLTPGM PGM(&PGM) 


Here again the value is viewed by the system as a single character string, not as 
two objects (a library and an object). If a qualified name must be handled as a 
single variable with a character string value, you can use the built-in function 
%SUBSTRING and the *TCAT concatenation Hee to_assign object and libra 
names to separate variables. See 
and Chapter J for examples cone (he %SUBSTRING function 


Lowercase Characters in Variables 


Reserved values, such as *LIBL, that can be used as variables must always be 
expressed in uppercase letters, especially if they are presented as character strings 
enclosed in apostrophes. For instance, if you wanted to substitute a variable for a 
library name on a command, the correct code is as follows: 


DCL VAR(&LIB) TYPE(*CHAR) LEN(10) VALUE('*LIBL') 
DLTPGM &LIB/MYPROG; 


However, it would be incorrect to specify the VALUE parameter this way: 
DCL VAR(&LIB) TYPE(*CHAR) LEN(10) VALUE('*1ib1') 


Note that if this VALUE parameter had not been enclosed in apostrophes, it would 
have been correct, because without the apostrophes it would be translated to 
uppercase automatically. This error frequently occurs when the parameter is passed 
as input to a procedure or program from a display as a character string, and the 
display entry is made in lowercase. 


Note: The above paragraph does not take into account the fact that translation to 


uppercase is language dependent. REMEMBER: Relying on the system to 
translate values to uppercase may produce unexpected results. 
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Variables Replacing Reserved or Numeric Parameter Values 


Some CL commands allow both numeric or predefined (reserved) values on certain 
parameters. Where this is true, you can also use character variables to represent the 
value on the command parameter. 


Each parameter on a command can accept only certain types of values. The 
parameter may allow an integer, a character string, a reserved value, a variable of 
a specified type, or some mixture of these, as values. Some types of values are 
required for parameters. If the parameter allows numeric values (if the value is 
defined in the command as *INT2, *INT4, *UINT2, *UINT4, or *DEC) and also 
allows reserved values (a character string preceded by an asterisk), you can use a 
variable as the value for the parameter. The variable must be declared as 
TYPE(*CHAR) if you intend to use a reserved value. 


For example, the Change Output Queue (CHGOUTQ) command has a job 
separator (JOBSEP) parameter that can have a value of either a number (0 through 
9) or the predefined default, *SAME. Because both the number and the predefined 
value are acceptable, you can also write a CL procedure that substitutes a character 
variable for the JOBSEP value: 

PGM 

DCL &NRESP *CHAR LEN(6) 

DCL &SEP *CHAR LEN(4) 


DCL &FILNAM *CHAR LEN(10) 
DCL &FILLIB *CHAR LEN(10) 


LOOP: SNDRCVF..... 
IF (&SEP *EQ IGNR) GOTO END 
ELSE IF (&SEP *EQ NONE) CHGVAR &NRESP '0! 
ELSE IF (&SEP *EQ NORM) CHGVAR &NRESP '1' 
ELSE IF (&SEP *EQ SAME) CHGVAR &NRESP '*SAME! 
CHGOUTQ OUTQ(&FILLIB/&FILNAM) JOBSEP(&NRESP) 
GOTO LOOP 

END: RETURN 
ENDPGM 


In the preceding example, the display station user enters information on a display 
describing the number of job separators desired for a specified output queue. The 
variable &NRESP is a character variable manipulating numeric and predefined 
values (note the use of apostrophes). The JOBSEP parameter on the CHGOUTQ 
command will recognize these values as if they had been entered as numeric or 
predefined values. The DDS for the display file used in this program should use 
the VALUES keyword to restrict the user responses to IGNR, NONE, NORM, or 
SAME. 


If the parameter allows a numeric type of value (*INT2, *INT4, *UINT2, UINT4, or 
*DEC) and you do not intend to enter any reserved values (such as *SAME), then 
you can use a decimal variable in that parameter. 

You can find information about the types of values that are allowed by command 
parameters in Chapter J of this manual. The CL section of the Programming 


category in the iSeries Information Center contains additional information. 


Another alternative for this function is to use the prompter within CL procedures. 
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Changing the Value of a Variable 


You can change the value of a CL variable using the Change Variable (CHGVAR) 
command. The value can be changed: 


¢ To a constant: 
CHGVAR VAR(&INVCMPLT) VALUE (0) 


or 
CHGVAR &INVCMPLT 0 


&INVCMPLT is set to 0. 
¢ To the value of another variable: 
CHGVAR VAR(&A) VALUE (&B) 


or 
CHGVAR &A &B 


&A is set to the value of the variable &B 
* To the value of an expression after it is evaluated: 
CHGVAR VAR(8A)  VALUE(8A + 1) 


or 
CHGVAR 8A (8A + 1) 


The value of &A is increased by 1. 


* To the value produced by the built-in function %SST (see (Using the 
1 for more information): 


CHGVAR VAR(&A)  VALUE(%SST(&B 1 5)) 


&A is set to the first five characters of the value of the variable &B 


* To the value produced by the built-in function %SWITCH (see Using thd 
age 45 for more information): 


CHGVAR VAR (8A) VALUE (%SWITCH(OXX111X0) 


&A is set to 1 if job switches 1 and 8 are 0 and job switches 4, 5 and 6 are 1; 
otherwise, &A is set to 0. 


7 us the value produced by the built-in function %BIN (see (Using the %BINAR 
for more information): 
CHGVAR VAR(8A) ule esthc es 1 4)) 


The first four characters of variable &B are converted to the decimal equivalent 
and stored in decimal variable &A 


The CHGVAR command can be used to retrieve and to change the local data area 
also. For example, the following commands blank out 10 bytes of the local data 
area and retrieve part of the local data area: 


CHGVAR %SST(*LDA 1 10) ' ' 


CHGVAR &A %SST(*LDA 1 10) 
For a logical variable, the value to which the variable is to be changed must be a 


logical value. For decimal variables, a decimal or character value can be used. For 
character variables, either character or decimal values are accepted. 
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When specifying a decimal value for a character variable, remember the following: 


* The value of the character variable is right-justified and, if necessary, padded 
with leading zeros. 


* The character variable must be long enough to contain a decimal point and a 
minus (-) sign, when necessary. 


* When used, a minus (-) sign is placed in the leftmost position of the value. 


For example, &A is a character variable to be changed to the value of the decimal 
variable &B The length of &A is 6. The length and decimal positions of &B are 5 
and 2, respectively. The current value of &B is 123. The resulting value of &A is 
123.00. 


When specifying a character value for a decimal variable, remember the following: 


* The decimal point is determined by the placement of a decimal point in the 
character value. If the character value does not contain a decimal point, the 
decimal point is placed in the rightmost position of the value. 


* The character value can contain a minus (-) sign or plus (+) sign immediately to 
the left of the value; no intervening blanks are allowed. If the character value 
has no sign, the value is assumed to be positive. 


* If the character value contains more characters to the right of the decimal point 
than can be contained in the decimal variable, the characters are truncated. 
However, if the excess characters are to the left of the decimal point, they are not 
truncated and an error occurs. 


For example, &C is a decimal variable to be changed to the value of the 
character variable &D The length of &C is 5 with 2 decimal positions. The 
length of &D is 10 and its current value is +123.1bbbb (where b=blank). The 
resulting value of &C is 123.10. 


Trailing Blanks on Command Parameters 


Some command parameters are defined with the parameter value of VARY(*YES). 
This parameter value causes the length of the value passed to be the number of 
characters between the apostrophes. When a CL variable is used to specify the 
value for a parameter defined in this way, the system removes trailing blanks 
before determining the length of the variable to be passed to the command 
processor program. If the trailing blanks are present and are significant for the 
parameter, you must take special actions to ensure that the length passed includes 
them. Most command parameters are defined and used in ways which do not 
cause this condition to occur. An example of a parameter defined where this 
condition is likely to occur is the key value element of the POSITION parameter on 
the OVRDBF command. 


When this condition could occur, the desired result can be attained for these 
parameters by constructing a command string that delimits the parameter value 
with apostrophes and passing the string to QCEMDEXC or QCAPCMD for 
processing. 


The following is an example of a program that can be used to run the OVRDBF 
command so that the trailing blanks are included as part of the key value. This 
same technique can be used for other commands that have parameters defined 
using the parameter VARY(*YES); trailing blanks must be passed with the 
parameter. 
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PGM PARM(&KEYVAL &LEN) 


/* PROGRAM TO SHOW HOW TO SPECIFY A KEY VALUE WITH TRAILING */ 
/* BLANKS AS PART OF THE POSITION PARAMETER ON THE OVRDBF */ 
/* COMMAND IN A CL PROGRAM. */ 
/* THE KEY VALUE ELEMENT OF THE POSITION PARAMETER OF THE OVRDBF  */ 
/* COMMAND IS DEFINED USING THE VARY(*YES) PARAMETER. */ 
/* THE DESCRIPTION OF THIS PARAMETER ON THE ELEM COMMAND */ 
/* DEFINITION STATEMENT SPECIFIES THAT IF A PARAMETER */ 
/* DEFINED IN THIS WAY IS SPECIFIED AS A CL VARIABLE THE */ 
/* LENGTH IS PASSED AS THE VARIABLE WITH TRAILING BLANKS */ 
/* REMOVED. A CALL TO QCMDEXC USING APOSTROPHES TO DELIMIT */ 
/* THE LENGTH OF THE KEY VALUE CAN BE USED TO CIRCUMVENT */ 
/* THIS ACTION. */ 
/* PARAMETERS-- */ 
DCL VAR(&KEYVAL) TYPE(*CHAR) LEN(32) /* THE VALUE + 
OF THE REQUESTED KEY. NOTE IT IS DEFINED AS + 
32 CHAR. */ 
DCL VAR(&LEN) TYPE(*DEC) LEN(15 5) /* THE LENGTH + 


OF THE KEY VALUE TO BE USED. ANY VALUE OF + 
1 TO 32 CAN BE USED */ 


/* THE STRING TO BE FINISHED FOR THE OVERRIDE COMMAND TO BE */ 
/* PASSED TO QCMDEXC (NOTE 2 APOSTROPHES TO GET ONE). */ 
DCL VAR(&STRING) TYPE(*CHAR) LEN(100) + 
VALUE('OVRDBF FILE(X3) POSITION(*KEY 1 FMT1 '' ') 
/* POSITION MARKER 123456789 123456789 123456789 123456789 x/ 
DCL VAR(&END) TYPE(*DEC) LEN(15 5) /* A VARIABLE + 


TO CALCULATE THE END OF THE KEY IN &STRING */ 


CHGVAR VAR(%SST(&STRING 40 &LEN)) VALUE(&KEYVAL) /* + 
PUT THE KEY VALUE INTO COMMAND STRING FOR + 
QCMDEXC IMMEDIATELY AFTER THE APOSTROPHE. */ 

CHGVAR VAR(&END) VALUE(&LEN + 40) /* POSITION AFTER + 
LAST CHARACTER OF KEY VALUE */ 

CHGVAR VAR(%SST(&STRING &END 2)) VALUE('')') /* PUT + 
A CLOSING APOSTROPHE & PAREN TO END + 
PARAMETER */ 

CALL PGM(QCMDEXC) PARM(&STRING 100) /* CALL TO + 
PROCESS THE COMMAND «/ 

ENDPGM 


Note: If you use VARY(*YES) and RTNVAL(*YES) and are passing a CL variable, 
the length of the variable is passed rather than the length of the data in the 
CL variable. 


Writing Comments in CL Procedures 


When you want to write comments in your CL procedures or add comments to 
commands in your procedures, use the character pairs /* and */. The comment is 
written between these symbols. 


The starting comment delimiter, /*, requires three characters unless the /* 
characters appear in the first two positions of the command string. In the latter 
situation, /* can be used without a following blank before a command. 


You can enter the three-character starting comment delimiters in any of the 
following ways (b represents a blank): 

/*b 

b/* 

[** 


Therefore, the starting comment delimiter can be entered four ways. The starting 
comment delimiter, /*, can: 


* Begin in the first position of the command string 
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* Be preceded by a blank 
* Be followed by a blank 
* Be followed by an asterisk (/**). 


Note: A comment cannot be imbedded within a comment. 


For example, in the following procedure, comments are written to describe possible 
user responses to a set of menu options: 


PGM /* ORDO40C Order dept general menu */ 
DCLF FILE(ORDO40CD) 
START: SNDRCVF RCDFMT (MENU) 
IF (&RESP=1) THEN(CALL CUS210) 
/*Customer inquiry */ 
ELSE + 
IF (&RESP=2) THEN(CALL ITM210) 
/*xItem inquiry */ 
ELSE + 
IF (&RESP=3) THEN(CALL CUS210) 
/* Customer name search */ 
ELSE + 
IF (&RESP=4) THEN(CALL ORD215) 
/** Orders by cust */ 
ELSE + 
IF (&RESP=5) THEN(CALL ORD220) 
/* Existing order */ 
ELSE + 
IF (&RESP=6) THEN(CALL ORD410C) 
/*x* Order entry */ 
ELSE + 
IF (&RESP=7) THEN(RETURN) 
GOTO START 
ENDPGM 


Controlling Processing within a CL Procedure 


Commands in a CL procedure are processed in consecutive sequence. Each 
command is processed, one after another, in the sequence in which it is 
encountered. You can alter this consecutive processing using commands that 
change the flow of logic in the procedure. These commands can be conditional (IF) 
or unconditional (GOTO). 


Unconditional branching means that you can instruct processing to branch to 
commands or sets of commands located anywhere in the procedure without regard 
to what conditions exist at the time the branch instruction is processed. You can do 
this with the GOTO command. 


Conditional branching means that under certain specified conditions, processing 
may branch to sections or commands that are not consecutive within the 
procedure. The branching may be to any statement in the procedure. This is called 
conditional processing because the branching only occurs when the specified 
condition is true. Conditional processing is usually associated with the IF 
command. With the ELSE command, you can specify alternative processing if the 
condition is not true. 


The DO command allows you to create groups of commands that are always 
processed together, as a group, under specified conditions. 
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Using the GOTO Command and Labels 


The GOTO command processes an unconditional branch. With the GOTO 
command, processing is directed to another part (identified by a label) of the 
procedure whenever the GOTO command is encountered. This branching does not 
depend on the evaluation of an expression. After the branch to the labeled 
statement, processing begins at that statement and continues in consecutive 
sequence; it does not return to the GOTO command unless specifically directed 
back by another instruction. You can branch forward or backward. You cannot use 
GOTO to go to a label outside the procedure. The GOTO command has one 
parameter, which contains the label of the statement branched to: 


GOTO CMDLBL(label) 


A label identifies the statement in the procedure to which processing is directed by 
the GOTO command. To use a GOTO command, the command you are branching 
to must have a label. 


PGM 


START: SNDRCVF RCDFMT (MENU) 
IF (&RESP=1) THEN(CALL CUS210) 


GOTO START 


ENDPGM 


The label in this example is START. A label can have as many as 10 characters and 
must be immediately followed by a colon, but blanks can occur between the label 
and the command name. 


Using the IF Command 


The IF command is used to state a condition that, if true, specifies some statement 
or group of statements in the procedure to be run. The ELSE command can be 
used with the IF command to specify a statement or group of statements to be run 
if the condition expressed by the IF command is false. 


The command includes an expression, which is tested (true or false), and a THEN 
parameter that specifies the action to be taken if the expression is true. The IF 
command is formatted as follows: 


IF COND(logical-expression) THEN(CL-command) 


The logical expression on the COND parameter may be a single logical variable or 
constant, or it must describe a relationship between two or more operands; the 


expression is then evaluated as true or false. See ULUsing the *AND, *OR, and *NOT 
Bee aed for more detailed information on the construction of logical 


expressions. 


If the condition described by the logical expression is evaluated as true, the 


procedure processes the CL command on the THEN parameter. This may be a 
single command, or a group of commands (see [Tising the DO Command and DO 
SRLS ET | If the condition is not true, the procedure runs the next 
sequential command. 
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Both COND and THEN are keywords on the command, and they can be omitted 
for positional entry. The following are syntactically correct uses of this command: 
IF COND(&RESP=1) THEN(CALL CUS210) 


IF (&A *EQ &B) THEN(GOTO LABEL) 
IF (&A=&B) GOTO LABEL 


Blanks are required between the command name (IF) and the keyword (COND) or 
value (&A). No blanks are permitted between the keyword, if specified, and the 
left parenthesis enclosing the value. 


The following is an example of conditional processing with an IF command. 
Processing branches in different ways depending on the evaluation of the logical 
expression in the IF commands. Assume, for instance, that at the start of the 
following code, the value of &A is 2 and the value of &C is 4. 


IF (&A=2) THEN(GOTO FINAL) 
IF (&A=3) THEN(CHGVAR &C 5) 


FINAL: IF (&C=5) CALL PROGA 
ENDPGM 


In this case, the procedure processes the first IF command before branching to 
FINAL, skipping the intermediate code. It does not return to the second IF 
command. At FINAL, because the test for &C=5 fails, PROGA is not called. The 
procedure then processes the next command, ENDPGM, which signals the end of 
the procedure, and returns control to the calling procedure. 


Processing logic would be different if, using the same code, the initial values of the 
variables were different. For instance, if at the beginning of this code the value of 
&A is 3 and the value of &C is 4, the first IF statement is evaluated as false. 
Instead of processing the GOTO FINAL command, the procedure ignores the first 
IF statement and moves on to the next one. The second IF statement is evaluated 
as true, and the value of &C is changed to 5. Subsequent statements, not shown 
here, are also processed consecutively. When processing reaches the last IF 
statement, the condition &C=5 is evaluated as true, and PROGA is called. 


A series of consecutive IF statements are run independently. For instance: 


PGM /* IFFY x/ 

DCL 8A.. 

DCL &B.. 

DCL ac.. 

DCL &D.. 

DCL 8AREA *CHAR LEN(5) VALUE(YESNO) 

DCL &RESP.. 

IF (&A=&B) THEN(GOTO END) /* IF #1. */ 

IF (&C=8D) THEN(CALL PGMA) /* IF #2. »/ 

IF (&RESP=1) THEN(CHGVAR &C 2) /* IF #3 */ 
IF (%SUBSTRING(8AREA 1 3) *EQ YES) THEN(CALL PGMB) /* IF #4 «/ 
CHGVAR &B &C 


END: ENDPGM 


If, in this example, &A is not equal to &B, the next statement is run. If &C is equal 
to &D, PGMA is called. When PGMA returns, the third IF statement is considered, 
and so on. Note the difference in logic and processing between these simple 
sequential IF statements and the use of IF with ELSE or the use of embedded IF 
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An embedded command is a command that is completely enclosed in the 
parameter of another command. In the following examples, the CHGVAR 
command and the DO command are embedded: 


IF (8A *EQ &B) THEN(CHGVAR 8A (8&A+1)) 


IF (&B *EQ &C) THEN(DO) 


ENDDO 


Using the DO Command and DO Groups 


The DO command lets you process a group of commands together. The group is 
defined as all those commands between the DO command and the next ENDDO 
command. 


Processing of the group is usually conditioned on the evaluation of an associated 
command. Do groups are most frequently associated with the IF, ELSE, or 
MONMSG commands. For instance: 


IF (&A=&B) THEN(DO) 


Do Group 
ENDDO 


ENDPGM 
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If the logical expression (&A=&B) is true, then the Do group is processed. If the 
expression is not true, then processing starts after the ENDDO command; the Do 
group is skipped. 


In the following procedure, if &A is not equal to &B, the system calls PROCB. 
PROCA is not called, nor are any other commands in the Do group processed. 
Do groups can be nested within other Do groups, up to a maximum of 10 levels of 
IF (&A=8B) THEN(DO) | 

A 


CALLPRC PROC 


CHGVAR &A &B + Do Group 
SNDPGMMSG... J 


ENDDO 
CALLPRC PROCB 
CHGVAR &ACCTS &B 
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nesting. 


There are three levels of nesting in the following example. Note how each Do 
group is completed by an ENDDO command. 
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PGM 


IF (8A=&B) DO 

CALL PGMA 

IF (&A=5) DO 

CHGVAR &A 26 

CALL PGMB 

IF (&AREA=YES) DO 


First Nest 


Second CHGVAR 8AREA NO 
Nest Third Nest 4 CHGVAR &P (&P+2) 
ENDDO 
CALLPRC ACCTSPAY 
ENDDO 
ENDDO 
CALL PGMC 
ENDPGM 


RV3W199-0 


In this example, if &A in the first nest does not equal 5, PGMC is called. If &A 
does equal 5, the statements in the second Do group are processed. If &AREA in 
the second Do group does not equal YES, procedure ACCTSPAY is called, because 
processing moves to the next command after the Do group. 


The CL compiler does not indicate the beginning or ending of Do groups. If the CL 
compiler notes any unbalanced conditions, it is not easy to detect the actual errors. 


Using the ELSE Command 


The ELSE command is a way of specifying alternative processing if the condition 
on the associated IF command is false. 


The IF command can be used without the ELSE command: 


IF (&A=&B) THEN(CALLPRC PROCA) 
CALLPRC PROCB 


In this case, PROCA is called only if &A=&B, but PROCB is always called. 


If you use an ELSE command in this procedure, however, the processing logic 
changes. In the following example, if &A=&B, PROCA is called, and PROCB is not 
called. If the expression &A=8B is not true, PROCB is called. 

IF (&A=&B) THEN(CALLPRC PROCA) 


ELSE CMD(CALLPRC PROCB) 
CHGVAR &C 8 


The ELSE command must be used when a false evaluation of an IF expression 
leads to a distinct branch (that is, an exclusive either/or branch). 


The real usefulness of the ELSE command is best demonstrated when combined 
with Do groups. In the following example, the Do group may not be run, 
depending on the evaluation of the IF expression, but the remaining commands are 
always processed. 
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IF (&A=&B) THEN(DO) 
Conditioned-Run Only if True 


ENDDO 
CHGVAR &C 8 . 
SAVOBJ... Unconditioned-Run Whether or Not 
CALL PGM(PAYROLL) Expression Is True 
ENDPGM 
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With the ELSE command you can specify that a command or set of commands be 
processed only if the expression is not true, thus completing the logical 
alternatives: 


IF (&A=&B) THEN(DO) 


: Conditioned for True Only 
ENDDO 
ELSE DO 
: Conditioned for False Only 
ENDDO 
CHGVAR &C 8 


SAVOBJ... 7 
CALL PGM(PAYROLL) ¢ UNnconditioned 
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Each ELSE command must have an associated IF command preceding it. If nested 
levels of IF commands are present, each ELSE command is matched with the 
innermost IF command that has not already been matched with another ELSE 
command. 

IF tes. THEN sc 


IF ...THEN(DO) 
IF ...THEN(DO) 


ENDDO 
ELSE DO 
IF ...THEN(DO) 
ENDDO 
ELSE DO 
ENDDO 
ENDDO 
ELSE IF ... THEN ... 
IF ... THEN .. 
IF soo THEN sss 


In reviewing your procedure for matched ELSE commands, always start with the 
innermost set. 
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The ELSE command can be used to test a series of mutually exclusive options. In 
the following example, after the first successful IF test, the embedded command is 
processed and the procedure processes the RCLRSC command: 
IF COND(&OPTION=1) THEN(CALLPRC PRC(ADDREC) ) 

ELSE | CMD(IF COND(&OPTION=2) THEN(CALLPRC PRC(DSPFILE) )) 

ELSE CMD(IF COND(&0PTION=3) THEN(CALLPRC PRC(PRINTFILE) )) 

ELSE CMD(IF COND(&0PTION=4) THEN(CALLPRC PRC (DUMP) ) ) 

RCLRSC 
RETURN 


Using Embedded IF Commands 


An IF command can be embedded in another IF command. This would occur 
when the command to be processed under a true evaluation (the CL command 
placed on the THEN parameter) is itself another IF command: 


IF (&8A=&B) THEN(IF (&C=&D) THEN(GOTO END) ) 
GOTO START 


This can be useful when several conditions must be satisfied before a certain 
command or group of commands is run. In the preceding example, if the first 
expression is true, the system then reads the first THEN parameter; within that, if 
the &C=&D expression is evaluated as true, the system processes the command in the 
second THEN parameter, GOTO END. Both expressions must be true to process 
the GOTO END command. If one or the other is false, the GOTO START command 
is run. Note the use of parentheses to organize expressions and commands. 


Up to 10 levels of such embedding are permitted in CL programming. 


As the levels of embedding increase and logic grows more complex, you may wish 
to enter the code in free-form design to clarify relationships: 
PGM 
DCL &A *DEC 1 
DCL &B *CHAR 2 
DCL &RESP *DEC 1 
IF (&RESP=1) + 

IF (&A=5) + 

IF (&B=NO) THEN(DO) 


ENDDO 
CHGVAR &A VALUE(8) 
CALL PGM(DAILY) 
ENDPGM 


The preceding IF series is handled as one embedded command. Whenever any one 
of the IF conditions fails, processing branches to the remainder of the code 
(CHGVAR and subsequent commands). If the purpose of this code is to 
accumulate a series of conditions, all of which must be true for the Do group to 
process, it could_be more easily coded_using *AND with several expressions in one 
command. See A 


In some cases, however, the branch must be different depending on which 
condition fails. You can accomplish this by adding an ELSE command for each 
embedded IF command: 

PGM 

DCL 8A ... 

DCL &B ... 

DCL &RESP ... 

IF (&RESP=1) + 
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IF (&A=5) + 
IF (&B=NO) THEN(DO) 


SNDPGMMSG ne 


ENDDO 
ELSE CALLPRC PROCA 
ELSE CALLPRC PROCB 
CHGVAR 8A 8 
CALLPRC PROC (DAILY) 
ENDPGM 


Here, if all conditions are true, the SNDPGMMSG command is processed, followed 
by the CHGVAR command. If the first and second conditions (&RESP=1 and &A=5) 
are true, but the third (&B=NO0) is false, PROCA is called; when PROCA returns, the 
CHGVAR command is processed. If the second conditions fails, PROCB is called 
(&B=NO is not tested), followed by the CHGVAR command. Finally, if &RESP does 
not equal 1, the CHGVAR command is immediately processed. The ELSE 
command has been used to provide a different branch for each test. 


Note: The following three examples are correct syntactical equivalents to the 
embedded IF command in the preceding example: 


IF (&RESP=1) THEN(IF (&A=5) THEN(IF (&B=NO) THEN(DO))) 


IF (&RESP=1) THEN + 
(IF (&A=5) THEN + 
(IF (&B=NO) THEN(DO))) 


IF (&RESP=1) + 
(IF (&A=5) + 
(IF (&B=NO) THEN(DO))) 


Using the *AND, *OR, and *NOT Operators 


*AND and *OR are the reserved values for logical operators used to specify the 
relationship between operands in a logical expression. The ampersand symbol (&) 
can replace the reserved value *AND, and the vertical bar (|) can replace *OR. The 
reserved values must be preceded and followed by blanks. The operands in a 
logical expression consist of relational expressions or logical variables or constants 
separated by logical operators. The *AND operator indicates that both operands 
(on either side of the operator) have to be true to produce a true result. The *OR 
operator indicates that one or the other of its operands must be true to produce a 
true result. 


Note: Using the ampersand symbol or the vertical bar can cause problems because 
the symbols are not at the same code point for all code pages. To avoid this, 
use *AND and *OR instead of the symbols. 


Use operators, other than logical operators, in expressions to indicate the actions to 
perform on the operands in the expression or the relationship between the 
operands. There are three kinds of operators other than logical operators: 


¢ Arithmetic (+, -, *, /) 
¢ Character (*CAT, ||, *BCAT, |>, *TCAT, |<) 
* Relational (*EQ, =, *GT, >, *LT, <, *GE, >=, *LE, <=, *NE, 7=, *NG, >>, *NL, ><) 


Chapter 2. CL Programming 37 


You can find information about these operators in the CL section of the 
Programming category in the iSeries Information Center. 


The following are examples of logical expressions: 


((&C *LT 1) *AND (&TIME *GT 1430)) 
(&C *LT 1 *AND &TIME *GT 1430) 
((&C < 1) & (&TIME>1430)) 

((&C< 1) & (&TIME>1430) ) 


In each of these cases, the logical expression consists of three parts: two operands 
and one operator (*AND or *OR, or their symbols). It is the type of operator 
(*AND or *OR) that characterizes the expression as logical, not the type of 
operand. Operands in logical expressions can be logical variables or other 
expressions, such as relational expressions. (Relational expressions are 
characterized by &gt, &lt, or = symbols or corresponding reserved values.) For 
instance, in the example: 


((&C *LT 1) *AND (&TIME *GT 1430)) 


the entire logical expression is enclosed in parentheses, and both operands are 
relational expressions, also enclosed separately in parentheses. As you can see from 
the second example of logical expressions, the operands need not be enclosed in 
separate parentheses, but it is recommended for clarity. Parentheses are not needed 
because *AND and *OR have different priorities. *AND is always considered 
before *OR. For operators of the same priority, parentheses can be used to control 
the order in which operations are performed. 


A simple relational expression can be written as the condition in a command: 
IF (&A=&B) THEN(DO) 


ENDDO 
The operands in this relational expression could also be constants. 


If you wish to specify more than one condition, you can use a logical expression 
with relational expressions as operands: 


IF ((&A=&B) *AND (&C=8D)) THEN(DO) 


ENDDO 


The series of Sacer: IF commands cited as an example in KUsing Embedded TH 


could be coded: 


PGM 

DCL &RESP *DEC 1 

DCL 8A *DEC 1 

DCL &B *CHAR 2 

IF ((&RESP=1) *AND (&A=5) *AND (&B=NO)) THEN(DO) 


ENDDO 
CHGVAR 8A VALUE(8) 
CALLPRC PROC(DAILY) 
ENDPGM 


Here the logical operators are again used between relational expressions. 
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Because a logical expression can also have other logical expressions as operands, 
quite complex logic is possible: 
IF (((&8A=&8B) *OR (&A=&C)) *AND ((&C=1) *OR (&D='0'))) THEN(DO) 


In this case, &D is defined as a logical variable. 


The result of the evaluation of any relational or logical expression is a ‘1’ or ’0’ 
(true or false). The dependent command is processed only if the complete 
expression is evaluated as true (’1’). The following command is interpreted in these 
terms: 


IF ((&8A = &B) *AND (&C = &D)) THEN(DO) 


((true'1') *AND (not true'@')) 
(not true '0') 


The expression is finally evaluated as not true (’0’), and, therefore, the DO is not 
processed. For an explanation of how this evaluation was reached, see the matrices 
later in this section. 


This same process is used to evaluate a logical expression using logical variables, 
as in this example: 

PGM 

DCL &A *LGL 

DCL &B *LGL 

IF (&A\ *OR &B) THEN(CALL PGM(PGMA) ) 


ENDPGM 


Here the conditional expression is evaluated to see if the value of &A or of &B is 
equal to ‘1’ (true). If either is true, the whole expression is true, and PGMA is 
called. 


The final evaluation arrived at for all these examples of logical expressions is based 
on standard matrices comparing two values (referred to here as &A and &B) under 
an *OR or *AND operator. 


Use the following matrix when using *OR with logical variables or constants: 


If &A is: 

‘0’ 40 a 1’ 
and &B is: 

‘0’ al Kd ‘0’ i 


the OR expression is: 
‘0’ ial a 'Y’ i ld 


In short, for multiple OR operators with logical variables or constants, the 
expression is false (’0’) if all values are false. The expression is true ('1’) if any 
values are true. 

PGM 

DCL &A *LGL VALUE('O') 

DCL &B *LGL VALUE('1') 

DCL &C *LGL VALUE('1') 

IF (8A *OR &B *OR &C) THEN(CALL PGMA) 
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ENDPGM 


Here the values are not all false; therefore, the expression is true, and PGMA is 
called. 


Use the following matrix when evaluating a logical expression with *AND with 
logical variables or constants: 


If &A is: 

‘0’ ‘0’ al lid a li 
and &B is: 

‘0’ at lig 40" i lid 


the ANDed expression is: 
4)! 107 40" a lid 


For multiple AND operators with logical variables or constants, the expression is 
false (’0’) when any value is false, and true when they are all true. 

PGM 

DCL &A *LGL VALUE('0') 

DCL &B *LGL VALUE(‘1') 

DCL &C *LGL VALUE('1') 

IF (&A *AND &B *AND &C) THEN(CALL PGMA) 


ENDPGM 


Here the values are not all true; therefore, the expression is false, and PGMA is not 
called. 


These logical operators can only be used within an expression when the operands 
represent a logical value, as in the preceding examples. It is incorrect to attempt to 
use OR or AND for variables that are not logical. For instance: 

PGM 

DCL &A *CHAR 3 

DCL &B *CHAR 3 

DCL &C *CHAR 3 


Incorrect: IF (& *OR &B *OR &C = YES) THEN... 


The correct coding for this would be: 
IF ((&A=YES) *OR (&B=YES) *OR (&C=YES)) THEN... 


In this case, the ORing occurs between relational expressions. 


The logical operator *NOT (or 7) is used to negate logical variables or constants. 
Any *NOT operators must be evaluated before the *AND or *OR operators are 
evaluated. Any values that follow *NOT operators must be evaluated before the 
logical relationship between the operands is evaluated. 

PGM 

DCL &A *LGL ‘1! 

DCL &B *LGL '0' 

IF (&A *AND *NOT &B) THEN(CALL PGMA) 
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In this example, the values are all true; therefore, the expression is true, and 
PGMA is called. 

PGM 

DCL &A *LGL 

DCL &B *CHAR 3 VALUE('ABC') 

DCL &C *CHAR 3 VALUE('XYZ') 

CHGVAR &A VALUE(&B *EQ &C) 

IF (&A) THEN(CALLPRC PROCA) 


In this example, the value is false, therefore, PROCA is not called. 


For more information about logical and relational expressions, see the CL section of 
the Programming category in the iSeries Information Center. 


Using the %BINARY Built-In Function 


The binary built-in function (%BINARY or %BIN) interprets the contents of a 
specified CL character variable as a signed binary integer. The starting position 
begins at the position specified and continues for a length of 2 or 4 characters. 


The syntax of the binary built-in function is: 
%BINARY (character-variable-name starting-position length) 


or 
%BIN(character-variable-name starting-position length) 


The starting position and length are optional. However, if the starting position and 
length are not specified, a starting position of 1 and length of the character variable 
that is specified are used. In that case, you must declare the length of the character 
variable as either 2 or 4. 


If the starting position is specified, you must also specify a constant length of 2 or 4. 
The starting position must be a positive number equal to or greater than 1. If the 
sum of the starting position and the length is greater than the length of the 
character variable, an error occurs. (A CL decimal variable may also be used for 
the starting position.) 


You can use the binary built-in function with both the IF and CHGVAR 
commands. It can be used by itself or as part of an arithmetic or logical expression. 
You can also use the binary built-in function on any command parameter that is 
defined as numeric (TYPE of *DEC, *INT2, *INT4, *UINT2, or *UINT4) with 
EXPRCYES). 


When the binary built-in function is used with the condition (COND) parameter on 
the IF command or with the VALUE parameter on the Change Variable (CHGVAR) 
command, the contents of the character variable is interpreted as a 
binary-to-decimal conversion. 


When the binary built-in function is used with the VAR parameter on the 
CHGVAR command, the decimal value in the VALUE parameter is converted to a 
2-byte or 4-byte signed binary integer and the result stored in the character 
variable at the starting position specified. Decimal fractions are truncated. 


The system uses the binary built-in function on the RTNVAL parameter of the 


CALLPRC command to indicate that the calling procedure expects the called 
procedure to return a signed binary integer. 
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A 2-byte character variable can hold signed binary integer values from -32 768 
through 32 767. A 4-byte character variable can hold signed binary integer values 
from -2 147 483 648 through 2 147 483 647. 


The following are examples of the binary built-in function: 
* DCL VAR(&B2) TYPE(*CHAR) LEN(2)  VALUE(X'001C') 
DCL VAR(&N)  TYPE(*DEC) LEN(3 0) 
CHGVAR &N %BINARY(&B2) 


The contents of variable &B2 is treated as a 2-byte signed binary integer and 
converted to its decimal equivalent of 28. It is then assigned to the decimal 
variable &N 

° DCL VAR(&N) TYPE(*DEC) LEN(5 0) VALUE(107) 
DCL VAR(&B4) TYPE(*CHAR) LEN(4) 
CHGVAR %BIN(&B4) &N 


The value of the decimal variable &N is converted to a 4-byte signed binary 
number and is placed in character variable &B4 Variable &B4 will have the 
value of X'0000006B'. 


* DCL VAR(&P) TYPE(*CHAR) LEN(100) 
DCL VAR(&L) TYPE(*DEC)  LEN(5 0) 
CHGVAR &L VALUE(%BIN(&P 1 2) * 5) 


The first two characters of variable &P is treated as a signed binary integer, 
converted to its decimal equivalent, and multiplied by 5. The product is 
assigned to the decimal variable &L. 

* DCL VAR(&X) = TYPE(*CHAR) LEN(50) 
CHGVAR %BINARY(&X 15 2) VALUE(122.56) 


The number 122.56 is truncated to the whole number 122 and is then converted 
to a 2-byte signed binary integer and is placed at positions 15 and 16 of the 
character variable &X. Positions 15 and 16 of variable &X will contain the 
hexadecimal equivalent of X'007A’. 

* DCL VAR(&B4) TYPE(*CHAR) LEN(4) 
CHGVAR %BIN(&B4) VALUE(-57) 


The value -57 is converted to a 4-byte signed binary integer and assigned to the 
character variable &B4. The variable &B4 will then contain the value 
X'FFFFFFC7'. 

* DCL VAR(&B2) TYPE(*CHAR) LEN(2) VALUE(X'FF1B') 
DCL VAR(&C5) TYPE(*CHAR) LEN(5) 
CHGVAR &C5 %BINARY(&B2) 


The contents of variable &B2 is treated as a 2-byte signed binary integer and 
converted to its decimal equivalent of -229. The number is converted to character 
form and stored in the variable character &C5. The character variable &C5 will 
then contain the value ‘-0229&csq. 


° DCL VAR(&C5) TYPE(*CHAR) LEN(5)  VALUE(' 1253') 
DCL VAR(&B2) TYPE(*CHAR) LEN(2) 
CHGVAR %BINARY(&B2) VALUE(&C5) 


The character number 1253 in character variable &C5 is converted to a decimal 
number. The decimal number 1253 is then converted to a 2-byte signed binary 
integer and stored in the variable &B2. The variable &B2 will then have the 
value X'04E5'. 
* DCL -VAR(&S) TYPE(*CHAR) LEN(100) 
IF (%BIN(&S 1 2) *GT 10) 
THEN( SNDPGMMSG MSG('Too many in list.') ) 
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The first 2 bytes of the character variable &S are treated as a signed binary 
integer when compared to the number 10. If the binary number has a value 
larger than 10, then the SNDPGMMSG (Send Program Message) command is 
run. 


* DCL — VAR(&RTNV) TYPE(*CHAR) LEN(4) 
CALLPRC PRC(PROCA) RTNVAL(%BIN(&RTNV 1 4)) 


Procedure PROCA returns a 4-byte integer which is stored in variable &RTNV. 


Using the %SUBSTRING Built-In Function 


The substring built-in function (YSUBSTRING or%SST) produces a character string 
that is a subset of an existing character string and can only be used within a CL 
procedure. Ina CHGVAR command, the %SST function can be specified in place of 
the variable (VAR parameter) to be changed or the value (VALUE parameter) to 
which the variable is to be changed. In an IF command, the %SST function can be 
specified in the expression. 


The format of the substring built-in function is: 
%SUBSTRING(character-variable-name starting-position length) 


or 
%SST(character-variable-name starting-position length) 


You can code *LDA in place of the character variable name to indicate that the 
substring function is performed on the contents of the local data area. 


The substring function produces a substring from the contents of the specified CL 
character variable or the local data area. The substring begins at the specified 
starting position (which can be a variable name) and continues for the length 
specified (which can also be a variable name). Neither the starting position nor the 
length can be 0 or negative. If the sum of the starting position and the length of 
the substring are greater than the length of the entire variable or the local data 
area, an error occurs. The length of the local data area is 1024. 


The following are examples of the substring built-in function: 


* If the first two positions in the character variable & NAME are IN, the program 
INV210 is called. The entire value of &NAME is passed to INV210 and the value 
of &ERRCODE is unchanged. Otherwise, the value of &ERRCODE is set to 99. 
DCL &NAME *CHAR VALUE (INVOICE) 

DCL &ERRCODE *DEC (2 0) 
IF (%SST(&NAME 1 2) *EQ 'IN') + 
THEN(CALL INV210 &NAME) 
ELSE CHGVAR &ERRCODE 99 

If the first two positions of &A match the first two positions of &B, the program 

CUS210 is called. 

DCL &A *CHAR VALUE (ABC) 

DCL &B *CHAR VALUE (DEF) 

IF (%SST(&A 1 2) *EQ %SUBSTRING(&B 1 2)) + 
CALL CUS210 

* Position and length can also be variables: This example changes the value of &X 
beginning at position &Y for the length &Z to 123. 


CHGVAR %SST(&X &Y &Z) 1123! 
° If &A is ABCDEFG before this CHGVAR command is run, &A is 
CHGVAR %SST(&A 2 3) '123' 
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A123EFG after the command runs. 

In this example, the length of the substring, 5, exceeds the length of the operand 
YES to which it is compared. The operand is padded with blanks so that the 
comparison is between YESNO and YESbb (where b is a blank). The condition is 
false. 


DCL VAR(&NAME) TYPE(*CHAR) LEN(5) VALUE(YESNO) 


IF (%SST (&NAME 1 5) *EQ YES) + 
THEN(CALL PROGA) 


If the length of the substring is shorter than the operand, the substring is 
padded with blanks for the comparison. For example: 


DCL VAR(&NAME) TYPE(*CHAR) LEN(5) VALUE(YESNO) 


IF (%SST(&NAME 1 3 ) *EQ YESNO) THEN(CALL PROG) 


This condition is false because YESbb (where bb is two blanks) does not equal 
YESNO. 


The value of the variable &A is placed into positions 1 through 10 of the local 
data area. 


CHGVAR %SST(*LDA 1 10) 8A 


If the concatenation of positions 1 through 3 of the local data area plus the 
constant ‘XYZ’ is equal to variable &A, then PROCA is called. For example, if 
positions 1 through 3 of the local data area contain ’ABC’ and variable &A has a 
value of ABCXYZ, the test is true and PROCA is called. 


IF (((%SST*LDA 1 3) *CAT 'XYZ') *EQ &A) THEN(CALLPRC PROCA) 


This procedure scans the character variable & NUMBER and changes any leading 
zeros to blanks. This can be used for simple editing of a field before displaying 
in a message. 


DCL &NUMBER *CHAR LEN(5) 
DCL &X *DEC LEN(3 0) VALUE(1) 


LOOP:IF (%SST(&NUMBER &X 1) *EQ '0') DO 
CHGVAR (%SST(&NUMBER &X 1)) ' ' /* Blank out */ 
CHGVAR &X (&X + 1) /* Increment */ 
IF (& *NE 4) GOTO LOOP 
ENDDO 


The following procedure uses the substring built-in function to find the first 


sentence in a 50-character field &INPUT and to place any remaining text in a field 
&REMAINDER It assumes that a sentence must have at least 2 characters, and no 
embedded periods. 


PGM (&INPUT &REMAINDER) /* SEARCH */ 

DCL &INPUT *CHAR LEN(50) 

DCL &REMAINDER *CHAR LEN(50) 

DCL &X *DEC LEN(2 0) VALUE(03) 

DCL &L *DEC LEN(2 0) /* REMAINING LENGTH */ 


SCAN: IF (%SST(&INPUT &X 1) *EQ '.') THEN(DO) 


CHGVAR VAR(&L) VALUE (50-&X) 

CHGVAR VAR(&X) VALUE (&X+1) 

CHGVAR VAR(&REMAINDER) VALUE(%SST(&INPUT &X &L)) 
RETURN 

ENDDO 
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IF (&X *EQ 49) THEN(RETURN) 
CHGVAR &X (&X+1) 

GOTO SCAN 

ENDPGM 


The procedure starts by checking the third position for a period. Note that the 
substring function checks &INPUT from position 3 to a length of 1, which is 
position 3 only (length cannot be zero). If position 3 is a period, the remaining 
length of &INPUT is calculated. The value of &X is advanced to the beginning of 
the remainder, and the remaining portion of &INPUT is moved to ¢REMAINDER. 


If position 3 is not a period, the procedure checks to see if it is at position 49. If so, 
it assumes that position 50 is a period and returns. If it is not at position 49, the 
procedure advances &X to position 4 and repeats the process. 


Using the %SWITCH Built-In Function 


The switch built-in function (%SWITCH) compares one or more of eight switches 
with the eight switch settings already established for the job and returns a logical 
value of ’0’ or ‘1’. The initial values of the switches for the job are determined first 
by the Create Job Description (CRTJOBD) command; the default value is 00000000. 
You can change this if necessary using the SWS parameter on the SBMJOB, 
CHGJOB, or JOB command; the default for these is the job description setting. 
Other high-level languages may also set job switches. 


If, in the comparison of your %SWITCH values against the job values, every switch 
is the same, a logical value of ‘1’ (true) is returned. If any switch tested does not 
have the value indicated, the result is a ’0’ (false). 


The syntax of the %SWITCH built-in function is: 
%SWITCH(8-character-mask) 


The 8-character mask is used to indicate which job switches are to be tested, and 

what value each switch is to be tested for. Each position in the mask corresponds 
with one of the eight job switches in a job. Position 1 corresponds with job switch 
1, position 2 with switch 2, and so on. Each position in the mask can be specified 
as one of three values: 0, 1, or X. 


0 The corresponding job switch is to be tested for a 0 (off). 
1 The corresponding job switch is to be tested for a 1 (on). 
X The corresponding job switch is not to be tested. The value in the switch 


does not affect the result of %SWITCH. 


If %SWITCH(OX111XX0) is specified, job switches 1 and 8 are tested for 0s; switches 3, 
4, and 5 are tested for 1s; and switches 2, 6, and 7 are not tested. If each job switch 
contains the value (1 or 0 only) shown in the mask, the result of %SWITCH is true 
i La 


Switches can be tested in a CL procedure to control the flow of the procedure. This 
function is used in CL procedures with the IF and CHGVAR commands. Switches 
can be changed in a CL procedure by the Change Job (CHGJOB) command. For CL 
procedures, these changes take effect immediately. 


%SWITCH with the IF Command 

On the IF command, %SWITCH can be specified on the COND parameter as the 
logical expression to be tested. In the following example, 0X111XX0 is compared to 
the predetermined job switch setting: 
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IF COND(%SWITCH(OX111XX0)) THEN(GOTO C) 


If job switches 1, 3, 4, 5, and 8 contain 0, 1, 1, 1, and 0, respectively, the result is 
true and the procedure branches to the command having the label C. If one or 
more of the switches tested do not have the values indicated in the mask, the 
result is false, and the branch does not occur. 


In the following example, switches control conditional processing in two 
procedures. 


SBMJOB JOB(APP502) JOBD(PAYROLL) CMD(CALL APP502) 
SWS (11000000) 


PGM /* CONTROL */ 

IF (%SWITCH(11XXXXXX)) CALLPRC PROCA 
IF (%SWITCH(1OXXXXXX)) CALLPRC PROCB 
IF (%SWITCH(Q1XXXXXX)) CALLPRC PROCC 
IF (%SWITCH(OQOXXXXXX)) CALLPRC PROCD 
ENDPGM 


PGM /* PROCA */ 

CALLPRC TRANS 

IF (%SWITCH(1XXXXXXX)) CALLPRC CUS520 
ELSE CALLPRC CUS521 

ENDPGM 


%SWITCH with the CHGVAR Command 

On the CHGVAR command, you can specify %SWITCH to change the value of a 
logical variable. The value of the logical variable is determined by the results of 
comparing your %SWITCH settings with the job switch settings. If the result of the 
comparison is true, the logical variable is set to ‘1’. If the result is false, the 
variable is set to ‘0’. For instance, if the job switch is set to 10000001 and this 
procedure is processed: 

PGM 


DCL &A *LGL 
CHGVAR VAR(&A) VALUE(%SWITCH(10000001) ) 


ENDPGM 


then the variable &A has a value of ’1’. 


Using the Monitor Message (MONMSG) Command 


Escape messages are sent to CL procedures by the commands in the CL procedures 
and by the programs and procedures they call. These escape messages are sent to 
tell the procedures that errors were detected and requested functions were not 
performed. CL procedures can monitor for the arrival of escape messages, and you 
can specify through commands how to handle the messages. For example, if a CL 
procedure tries to move a data area that has been deleted, an object-not-found 
escape message is sent to the procedure by the Move Object (MOVOBJ) command. 


Using the Monitor Message (MONMSG) command, you can direct a procedure to 
take predetermined action if specific errors occur during the processing of the 
immediately preceding command. The MONMSG command is used to monitor for 
escape, notify, or status messages sent to the call stack of the procedure in which 
the MONMSG command is used. The MONMSG command has the following 
parameters: 


MONMSG MSGID(message-identifier) CMPDTA(comparison-data) + 
EXEC (CL-command) 
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Each message that is sent for a specific error has a unique identifier. You can enter 
as many as 50 message identifiers on the MSGID parameter. (See the online help 
for messages and identifiers). The CMPDTA parameter allows even greater 
specification of error messages because you can check for a specific character string 
in the MSGDTA portion of the message. On the EXEC parameter, you can specify a 
CL command (such as a Call Program (CALL), Do (DO), or a Go To (GOTO)), 
which directs the procedure to perform error recovery. 


In the following example, the MONMSG command follows the Receive File 
(RCVF) command and, therefore, is only monitoring for messages sent by the 
RCVF command: 
READLOOP: RCVF /* Read a file record +*/ 

MONMSG MSGID(CPF0864) EXEC(GOTO CMDLBL(EOF)) 

/* Process the file record */ 

GOTO CMDLBL(READLOOP) /* Get another record +*/ 
EOF: /* End of file processing */ 


The escape message, CPF0864, is sent to the procedure’s invocation queue when 
there are no more records in the file to read. Because the example specifies 
MSGID(CPF0864), the MONMSG monitors for this condition. When it receives the 
message, the GOTO CMDLBL(EOF) command is run. 


You can also use the MONMSG command to monitor for messages sent by any 
command in a CL procedure. The following example includes two MONMSG 
commands. The first MONMSG command monitors for the messages CPFO001 and 
CPF1999; these messages might be sent by any command run later in the 
procedure. When either message is received from any of the commands running in 
the procedure, control branches to the command identified by the label EXIT2. 


The second MONMSG command monitors for the messages CPF2105 and 
MCH1211. Because no command is coded for the EXEC parameter, these messages 
are ignored. 

PGM 

DCL 

MONMSG MSGID(CPFQ001 CPF1999) EXEC(GOTO EXIT2) 

MONMSG MSGID(CPF2105 MCH1211) 


ENDPGM 


Message CPFO001 states that an error was found in the command that is identified 
in the message itself. Message CPF1999, which can be sent by many of the 
debugging commands, such as Change Program Variable (CHGPGMVAR), states 
that errors occurred on the command, but it does not identify the command in the 
message. 


All error conditions monitored for by the MONMSG command with the EXEC 
parameter specified (CPFO001 or CPF1999) are handled in the same way at EXIT2, 
and it is not possible to return to the next sequential statement after the error. You 
can avoid this by monitoring for specific conditions after each command and 
branching to specific error correction procedures. 


All error conditions monitored for by the MONMSG command without the EXEC 


parameter specified (CPF2105 or MCH1211) are ignored, and procedure processing 
continues with the next command. 
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If the error occurs when evaluating the expression on an IF command, the 
condition is considered false. In the following example, MCH1211 (divide by zero) 
could occur on the IF command. The condition would be considered false, and 
PROCA would be called. 


IF(&8A / &B *EQ 5) THEN(DLTF ABC) 
ELSE CALLPRC PROCA 


If you code the MONMSG command at the beginning of your CL procedure, the 
messages you specify are monitored throughout the program, regardless of which 
command produces these messages. If the EXEC parameter is used, only the 
GOTO command can be specified. 


You can specify the same message identifier on a procedure-level or a 
command-level MONMSG command. The command-level MONMSG commands 
take precedence over the procedure-level MONMSG commands. In the following 
example, if message CPFO001 is received on CMDB, CMDC is run. If message 
CPFO0001 is received on any other command in the procedure, the procedure 
branches to EXIT2. If message CPF1999 is received on any command, including 
CMDB, the procedure branches to EXIT2. 

PGM 

MONMSG MSGID(CPFOQQ1 CPF1999) EXEC(GOTO EXIT2) 

CMDA 

CMDB 

MONMSG MSGID(CPFOQ@1) EXEC(CMDC) 

CMDD 

EXIT2: ENDPGM 


Because many escape messages can be sent to a procedure, you must decide which 
ones you want to monitor for and handle. Most of these messages are sent to a 
procedure only if there is an error in the procedure. Others are sent because of 
conditions outside the procedure. Generally, a CL procedure should monitor for 
those messages that pertain to its basic function and that it can handle 
appropriately. For all other messages, OS/400 assumes an error has occurred and 
takes appropriate default action. 


For more information about handling messages in CL procedures, see Chapter 7 
and . 


Values That Can Be Used as Variables 


Retrieving System Values 


A system value contains control information for the operation of certain parts of 
the system. IBM supplies several types of system values. For example, QDATE and 
QTIME are date and time system values, which you set when OS/400 is started. 


You can bring system values into your procedure and manipulate them as 
variables using the Retrieve System Value (RTVSYSVAL) command: 


RTVSYSVAL SYSVAL(system-value-name) RTNVAR(CL-variable-name) 


The RTNVAR parameter specifies the name of the variable in your CL procedure 
that is to receive the value of the system value. 


The type of the variable must match the type of the system value. For character 


and logical system values, the length of the CL variable must equal the length of 
the value. For decimal values, the length of the variable must be greater than or 
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equal to the length of the system value. System value attributes are defined in the 
iSeries Information Center under the Systems Management category of 
information. 


System Value QTIME 
In the following example, QTIME is received and moved to a variable, which is 
then compared with another variable. 
PGM 
DCL VAR(&PWRDNTME) TYPE(*CHAR) LEN(6) VALUE('162500') 
DCL VAR(&TIME) TYPE(*CHAR) LEN(6) 
RTVSYSVAL SYSVAL(QTIME) RTNVAR(&TIME) 
IF (&TIME *GT &PWRDNTME) THEN(DO) 
SNDBRKMSG('Powering down in 5 minutes. Please sign off.') 
PWRDWNSYS OPTION(*CNTRLD) DELAY(300) RESTART(*NO) + 
IPLSRC (*PANEL) 


ENDDO 
ENDPGM 


See the Systems Management category of information in the iSeries Information 
Center for a list of system values and how you can change and display them. 


System Value QDATE 

In many applications, you may want to use the current date in your procedure by 
retrieving the system value QDATE and placing it in a variable. You may also 
want to change the format of that date for use in your procedure. To convert the 
format of a date in a CL procedure, use the Convert Date (CVTDAT) command. 


The format for the system date is the system value QDATFMT, which is initially 
MDY (monthdayyear). For example, 062488 is the MDY format for June 24 1988. 
You can change this format to the YMD, DMY, or the JUL (Julian) format. For 
Julian, the QDAY value is a 3-character value from 001 to 366. It is used to 
determine the number of days between two dates. You can also delete the date 
separators or change the character used as a date separator with the CVTDAT 
command. 


Note: The shipped value of QDATFMT varies according to country. 


The format for the CVTDAT command is: 


CVTDAT DATE(date-to-be-converted) TOVAR(CL-variable) + 
FROMFMT(old-format) TOFMT(new-format) + 
TOSEP (new-separators) 


The DATE parameter can specify a constant or a variable to be converted. Once the 
date has been converted, it is placed in the variable named on the TOVAR 
parameter. In the following example, the date in variable &DATE, which is 
formatted as MDY, is changed to the DMY format and placed in the variable 
&CVTDAT. 


CVTDAT — DATE(&DATE) TOVAR(&CVTDAT) FROMFMT(*MDY) TOFMT (*DMY) 
TOSEP(*SYSVAL) 


The date separator remains as specified in the system value QDATSEP. 
The CVTDAT command can be useful when creating objects or adding a member 
that uses a date as part of its name. For example, assume that a member must be 


added to a file using the current system date. Also, assume that the current date is 
in the MDY format and is to be converted to the Julian format. 
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PGM 

DCL &DATE6 *CHAR LEN(6) 

DCL &DATE5 *CHAR LEN(5) 

RTVSYSVAL QDATE RTNVAR(&DATE6) 

CVTDAT DATE(&DATE6) TOVAR(&DATE5) TOFMT(*JUL) TOSEP(*NONE) 
ADDPFM LIB1/FILEX MBR('MBR' *CAT &DATE5) 


ENDPGM 


If the current date is 5 January 1988, the added member would be named 
MBR88005. 


Remember the following when converting dates: 


* The length of the value in the DATE parameter and the length of the variable on 
the TOVAR parameter must be compatible with the date format. The length of 
the variable on the TOVAR parameter must be at least: 


1. For Non-Julian Dates possessing 2 digit years 
a. Use 6 characters when using no separators. 
July 28, 1978 would be written as 072878. 
b. Use 8 characters when using separators. 
July 28, 1978 would be written as 07-28-78. 
2. For Non-Julian Dates with 4-digit years 
a. Use 8 characters when using no separators. 
July 28, 1978 would be written as 07281978. 
b. Use 10 characters when using separators. 
July 28, 1978 would be written as 07-28-1978. 
3. For Julian dates with 2-digit years 
a. Use 5 characters when using no separators. 
December 31, 1996 would be written as 96365. 
b. Use 6 characters when using separators. 
December 31, 1996 would be written as 96-365. 
4. For Julian dates with 4-digit years, 
a. 7 characters are required when no separators are used. 
February 4, 1997 would be written as 1997035. 
b. 8 characters are required when separators are used. 
February 4, 1997 would be written as 1997-035. 


Error messages are sent for converted characters that do not fit in the variable. If 
the converted date is shorter than the variable, it is padded on the right with 
blanks. 


* In every date format except Julian, the month and day are 2-byte fields no 
matter what value they contain. The year may be either 2-byte or 4-byte fields. 
All converted values are right-justified and, when necessary, padded with 
leading zeros. 

* In the Julian format, day is a 3-byte field, and year is a 2-byte or 4-byte field. All 
converted values are right-justified and, when necessary, padded with leading 
Zeros. 
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The following is an alternative program that uses the ILE bindable API, Get 
Current Local Time (CEELOCT), to convert a date to Julian format. To create this 
program, you must use the CRTBNDCL command alone or the CRTCLMOD 


command and the CRTPGM command together. 


PGM 
DCL 
DCL 
DCL 
DCL 
DCL 


CALLPRC PRC(CEELOCT) 


&LILDATE 
&PICTSTR 
&JULDATE 
&SECONDS 
&GREG 


*CHAR 
*CHAR 
*CHAR 
*CHAR 
*CHAR 


LEN(4) 
LEN(5) 
LEN(5) 
8 

23 


PARMS (&LILDATE) 
&SECONDS 


&GREG 
*OMIT 


CALLPRC PRC(CEEDATE) + 

PARMS (&LILDATE) 
&PICTSTR 
&JULDATE 


ADDPGM 


ENDPGM 


*OMIT 


LIB1/FILEX MBR('MBR' 


VALUE (YYDDD) 

/* Seconds from CEELOCT */ 

/* Gregorian date from CEELOCT */ 

/* */ 

/* Get current date and time «/ + 

/* Date in Lilian format «/ + 

/* Seconds field will not be used */ 

/* Gregorian field will not be used */ 

/* Omit feedback parameter so exceptions + 
are signalled */ 

/* Today's date x/ + 

/* How to format x/ + 

/* Julian date «/ + 


*CAT &JULDATE') 


See the Programming category of information in the iSeries Information Center for 
more information on ILE API's. 


Retrieving Configuration Source 


Using the Retrieve Configuration Source (RTVCFGSRC) command, you can 


generate CL command source for creating existing configuration objects and place 
the source in a source file member. The CL command source generated can be used 
for the following: 


* Moving configurations from system to system 


* Maintaining on-site configurations 


* Saving configurations (without using SAVSYS) 


Retrieving Configuration Status 


Using the Retrieve Configuration Status (RTVCFGSTS) command, you can give 


applications the capability to retrieve configuration status from three configuration 


objects: line, controller, and device. The RTVCFGSTS command can be used in a 


CL procedure to check the status of a configuration description. 


Retrieving Network Attributes 


Using the Retrieve Network Attributes (RTVNETA) command, you can retrieve the 


network attributes of the system. These attributes can be changed using the 
Change Network Attributes (CHGNETA) command and displayed using the 


Display Network Attributes (DSPNETA) command. See the Systems Management 


category of information in the iSeries Information Center for more information 


about network attributes. 
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RTVNETA Example 

In the following example, the default network output queue and the library that 
contains it are retrieved, changed to QGPL/QPRINT, and later changed back to the 
previous value. 

PGM 

DCL VAR(&OUTQNAME) TYPE(*CHAR) LEN(10) 

DCL VAR(&OUTQLIB) TYPE(*CHAR) LEN(10) 

RTVNETA OUTQ(8OUTQNAME) OUTQLIB(&8OUTQLIB) 

CHGNETA OUTQ(QGPL/QPRINT) 


CHGNETA OUTQ (&0UTQLIB/&0UTQNAME) 
ENDPGM 


Retrieving Job Attributes 


You can retrieve the job attributes and place their values in a CL variable to control 
your applications. 


Job attributes are retrieved using the Retrieve Job Attribute (RTVJOBA) command. 
You can retrieve all job attributes, or any combination of them, with the RTVJOBA 
command. 


In the following CL procedure, a RTVJOBA command retrieves the name of the 
user who called the procedure. 

PGM 

/* ORD410C Order entry program ~*/ 

DCL &CLKNAM TYPE(*CHAR) LEN(10) 

DCL &NXTPGM TYPE(*CHAR) LEN(3) 


RTVJOBA USER(&CLKNAM) 

BEGIN: CALL ORD410S2 PARM(&NXTPGM &CLKNAM) 
/* Customer prompt */ 
IF (&NXTPGM *EQ 'END') THEN(RETURN) 


The variable &CLKNAM, in which the user name is to be passed, is first declared 
using a DCL command. The RTVJOBA command follows the declare commands. 
When the program ORD41082 is called, two variables, &NXTPGM and 
&CLKNAM, are passed to it. €NXTPGM is passed as blanks but could be changed 
by ORD41082. 


RTVJOBA Example 

Assume in the following CL procedure, an interactive job submits a program 
including the CL procedure to batch. A Retrieve Job Attributes (RTVJOBA) 
command retrieves the name of the message queue to which the job’s completion 
message is sent, and uses that message queue to communicate with the user who 
submitted the job. 

PGM 

DCL &MSGQ *CHAR 10 

DCL &MSGQLIB *CHAR 10 

DCL &MSGKEY *CHAR 4 

DCL &REPLY *CHAR 1 

DCL &ACCTNO *CHAR 6 
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RTVJOBA SBMMSGQ(&MSGQ) SBMMSGQLIB(&MSGQLIB) 
IF (&MSGQ *EQ '*NONE') THEN(DO) 

CHGVAR &MSGQ 'QSYSOPR' 

CHGVAR &MSGQLIB 'QSYS! 
ENDDO 


IF (. . . ) THEN(DO) 
SNDMSG:SNDPGMMSG MSG('Account number ' *CAT &ACCTNO *CAT ‘is + 
not valid. Do you want to cancel the update + 
(Y or N)?') TOMSGQ(&MSGQLIB/&MSGQ) MSGTYPE(*INQ) + 
KEYVAR (&MSGKEY ) 
RCVMSG MSGQ(*PGMQ) MSGTYPE(*RPY) MSGKEY(&MSGKEY) + 
MSG(&REPLY) WAIT (*MAX) 
IF (&REPLY *EQ 'Y') THEN(RETURN) 
ELSE IF (&REPLY «NE 'N') THEN(GOTO SNDMSG) 
ENDDO 


Two variables, &MSGQ and &MSGQLIB, are declared to receive the name and 
library of the message queue to be used. The RTVJOBA command is used to 
retrieve the message queue name and library name. Because it is possible that a 
message queue is not specified for the job, the message queue name is compared 
to the value *NONE. If the comparison is equal, no message queue is specified, 
and the variables are changed so that message queue QSYSOPR in library QSYS is 
used. Later in the procedure, when an error condition is detected, an inquiry 
message is sent to the specified message queue and the reply is received and 
processed. Some of the other possible uses of the RTVJOBA command are: 


* Retrieve one or more of the job attributes (such as output queue, library list) so 
that they can be changed temporarily and later restored to their original values. 


* Retrieve one or more of the job attributes for use in the SBMJOB command, so 
that the submitted job will have the same attributes as the submitting job. 


Retrieving Object Descriptions 


You can also use the Retrieve Object Description (RTVOBJD) command to return 
the descriptions of a specific object to a CL procedure. Variables are used to return 


the descriptions. You can use these descriptions to help you detect unused objects. 
For more information about retrieving object descriptions, see 


You can also use the Retrieve Object Description (QUSROBJD) application 
programming interface (API) to return the description of a specific object to a 
procedure. The system uses a variable to return the descriptions. For more 
information, see the CL section of the Programming category for the iSeries 
Information Center. 


Retrieving User Profile Attributes 


Using the Retrieve User Profile Attributes (RTVUSRPRF) command, you can 
retrieve the attributes of a user profile (except for the password) and place their 
values in CL variables to control your applications. On this command, you can 
specify either the 10-character user profile name or *CURRENT. 
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You can also monitor for escape messages after running the RTVUSRPRF 
command. See the CL section of the Programming category in the iSeries 
Information Center for more information. 


RTVUSRPRF Example 

In the following CL procedure, a RTVUSRPRF command retrieves the name of the 
user who called the procedure and the name of a message queue to which to send 
messages for that user: 

DCL &USR *CHAR 10 


DCL @&USRMSGQ *CHAR 10 
DCL @&USRMSGQLIB *CHAR 10 


RTVUSRPRF USRPRF(*CURRENT) RTNUSRPRF(&USR) + 
MGSQ(&USRMSGQ) MSGQLIB(&USRMSGQLIB) 


The following information is returned to the procedure: 

* &USR contains the user profile name of the user who called the program. 

* &USRMSGOQ contains the name of the message queue specified in the user 
profile. 

* &USRMSGOQLIB contains the name of the library containing the message queue 
associated with the user profile. 


Retrieving Member Description Information 


Using the Retrieve Member Description (RTVMBRD) command, you can retrieve 
information about a member of a database file for use in your applications. 


RTVMBRD Example 

In the following CL procedure, a RT'VMBRD command retrieves the description of 
a specific member. Assume a database file called MFILE exists in the current 
library (MYLIB) and contains 3 members (AMEMBER, BMEMBER, and 


CMEMBER). 
DCL &LIB TYPE(*CHAR) LEN(10) 
DCL &MBR TYPE(*CHAR) LEN(10) 
DCL &SYS TYPE(*CHAR) LEN(4) 


DCL &MTYPE  TYPE(*CHAR) LEN(5) 
DCL &CRTDATE TYPE(*CHAR) LEN(13) 
DCL &CHGDATE TYPE(*CHAR) LEN(13) 
DCL &TEXT TYPE(*CHAR) LEN(50) 
DCL &NBRRCD TYPE(*DEC) LEN(10 0) 
DCL &SIZE TYPE(*DEC) LEN(10 0) 
DCL &USEDATE TYPE(*CHAR) LEN(13) 
DCL &USECNT TYPE(*DEC) LEN(5 @) 
DCL &RESET  TYPE(*CHAR) LEN(13) 


RTVMBRD —- FILE(*CWeb siteIB/MYFILE) MBR(AMEMBER *NEXT) + 
RTNLIB(&LIB) RTNSYSTEM(&SYS) RTNMBR(&MBR) + 
FILEATR(&MTYPE) CRTDATE(&CRTDATE) TEXT(&TEXT) + 
NBRCURRCD(&NBRRCD) DTASPCSIZ(&SIZE) USEDATE(&USEDATE) + 
USECOUNT(&USECNT) RESETDATE (&RESET) 


The following information is returned to the procedure: 
* The current library name (MYLIB) is placed into the CL variable name &LIB 


* The system that MYFILE was found on is placed into the CL variable name 
&SYS (*LCL means the file was found on the local system, and *RMT means the 
file was found on a remote system.) 
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* The member name (BMEMBER), since BMEMBER is the member immediately 
after AMEMBER in a name ordered member list (*NEXT), is placed into the CL 
variable named &MBR 

* The file attribute of MYFILE is placed into the CL variable named &MTYPE 
(*DATA means the member is a data member, and *SRC means the file is a 
source member.) 

* The creation date of BMEMBER is placed into the CL variable called &€CRTDATE 

* The text used to describe BMEMBER is placed into the CL variable called 
&TEXT 

* The current number of records in BMEMBER is placed into the CL variable 
called &NBRRCD 

* The size of BMEMBER’s data space (in bytes) is placed into the CL variable 
called &SIZE 

* The date that BMEMBER was last used is placed into the CL variable called 
&USEDATE 

* The number of days that BMEMBER has been used is placed into the CL 


variable called €USECNT The start date of this count is the value placed into 
the CL variable called &RESET 


Working with CL Procedures 


ACL source procedure must be compiled into a module and bound into a 
program before it can be run. 


To create a CL program in one step, you can use the CRTBNDCL command and 
create a bound program with one module. 


You can also create a module with the CRTCLMOD command. The module must 
then be bound into a program or service program using the Create Program 
(CRTIPGM) or Create Service Program (CRTSRVPGM) command. 


The following CRTCLMOD command creates the module ORD040C and places it 
in library DSTPRODLB: 


CRTCLMOD MODULE (DSTPRODLB/ORDO40C) SRCFILE(QCLSRC) 
TEXT('Order dept general menu program') 


The source commands for ORDO040C are in the source file QCLSRC, and the source 
member name is ORDO40C. By default, a compiler listing is created. 


On the CRTBNDCL command, you can specify listing options and whether the 
program should operate under the program owner’s user profile. 


A program can run using either the owner’s user profile or the user’s user profile. 


CL procedures and programs are created using options on the Programming 
Development Manager (PDM) menu or the Programmer Menu so the CRTCLMOD 
or CRTBNDCL does not have to be directly entered. 


Logging CL Procedure Commands 


You can specify that most CL commands run in a CL procedure be written 
(logged) to the job log by specifying one of the following values on the LOG 
parameter on the CRTCLMOD or CRTBNDCL command when the procedure is 
compiled: 
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*JOB = This default value indicates that logging is to occur when the job’s logging 
option is on. The option is initially set for no logging, but it can be 
changed by the LOGCLPGM parameter on the CHGJOB command. 
Therefore, if you create the module or program with this value, you can 
alter the logging option for each job or several times within a job. 


*YES This value indicates that logging is to occur each time the CL procedure is 
run. It cannot be changed by the CHGJOB command. 


*NO _ This value indicates that no logging is to occur. It cannot be changed by 
the CHGJOB command. 


Because these values are part of the CRTCLMOD and CRTBNDCL commands, you 
must recompile the module or program to change them. 


When you specify logging, you should use the Remove Message (RMVMSG) 
command with care in order not to remove any logged commands from the job 
log. If you specify CLEAR(*ALL) on the RMVMSG command, any commands 
logged prior to running the RMVMSG command do not appear in the job log. This 
affects only the CL procedure containing the RMVMSG command and does not 
affect any logged commands for the preceding or following recursion levels. 


Not all commands are logged to the job log. Following is a list of commands that 
are not logged: 


CHGVAR DO GOTO 
DCL ELSE IF 

DCLF ENDDO MONMSG 
PGM ENDPGM CALLPRC 


If the logging option is on, logging messages are sent to the CL procedure’s 
message queue. If the CL procedure is running interactively, and the message level 
on the job’s LOG parameter is set to 4, you can press F10 (Display detail messages) 
to view the logging of all commands. You can print the log if the message level is 
4 and you specify *PRINT when you sign off. 


The log includes the time, program and procedure names, message texts, and 
command names. Command names are qualified as they are on the original source 
statement. Command parameters are also logged; if the parameter information is a 
CL variable, the contents of the variable are printed (except for the RTNVAL 
parameter). 


Logging of commands affects performance. 


CL Module Compiler Listings 


When you create a CL module, you can create various types of listings using the 
OPTION and OUTPUT parameters on the CRTCLMOD command. 


The OPTION parameter values and their meanings are: 
* *GEN or *NOGEN 

Whether a module is to be created (*GEN is the default). 
* *XREF or *NOXREF 


Whether a listing of cross-references to variables and data references in the 
source input is to be produced (*XREF is the default). 


56 0S/400 CL Programming V5R2 


The OUTPUT parameter values and their meanings are: 

* *PRINT - print listing 

* *NONE - no compiler listing 

The listing created by specifying the OUTPUT parameter is called a compiler listing. 


The following shows a sample compiler listing. The callout numbers refer to 
descriptions following the listing. 


a 

5763SS1 V3R1M0 940909 Control Language MYLIB/DUMPERR 05/06/94 11:12:55 Page 1 
PYOQMAM: 6. odd kM Re a ee we AH ke 7 DUMPERR 

MABRY <5. Sep. WGA Scar ape de Ab Sb A a ae tte MYLIB 
SOUPCE! FAME eof ee ger ces er a ee a, QCLSRC 

ITD RANY ie ea ce dey tod, 2. I a ee ea ¢ MYLIB 
Source member name ............ . + DUMPERR 05/06/94 10:42:26 Eq 
Source printing options. .......... :  *XREF *NOSECLVL *NOEVENTF 
USM PROTIe 6. ia. fee Se oe, ee ee we ow :  *USER 
Progtiain: VOQGING: ss se sy “sy See bee cat Ge ae ee Ee :  *J0B 
Default activation group .......... 2 *YES 
Replace program... 2... 6.2.2.0 ee ee et *VES 
Target release: s,s: is: ae cee sarcat aie ee ve a, dee ve :  V3R1M0 
AUBHOTTEY: 6: cine Geiss sae a8 fond, iae, alates tee, Jaca We :  *LIBCRTAUT 
SONG: SEQUENCE? 5.56 ae sa ep cas ey cel ee ee a oe :  *HEX 
Language identifier *JOBRUN 
MORE, 4: dc hohe He aS : Test program 
Optimization ..... :  *NONE 
Debugging: View 6.6.66 ewe ee : «STMT 
Compiler ... 1.6... ee ee ee ee ee ~~ IBM AS/400 Control Language Compiler [jj 


Control Language Source 
SEQNBR: Feces (TD cadtieen 2 neste SB aactees 4 aetna 5 maton, 0: coeteae LT sadtinslO-ecetonns 9: cedts, (DATE 


100- PGM 05/06/94 
200- DCL &ABC *CHAR 10 VALUE('THIS') 05/06/94 
300- DCL &XYZ *CHAR 10 VALUE('THAT') 05/06/94 
400- DCL &MNO *CHAR 10 VALUE('OTHER') 05/06/94 
500- CRTLIB LB(LARRY) 05/06/94 
* CPD0043 30 Keyword LB not valid for this command. [J 
600- DLTLIB LIB(MOE 05/06/94 
* CPD0013 30 A matching parenthesis not found. 
700- MONMSG CPFOQ00 EXEC(GOTO ERR) 05/06/94 
800- ERROR: 05/06/94 
900- CHGVAR 8ABC 'ONE' 05/06/94 
1000- CHGVAR &XYZ 'TWO' 05/06/94 
1100- CHGVAR &MNO 'THREE' 05/06/94 
1200- DMPCLPGM 05/06/94 
1300- ENDPGM 05/06/94 
xe xe * END OF SOURCE ** * * * 
5763SS1 V3R1M0 940909 Control Language MYLIB/DUMPERR 05/06/94 11:12:55 Page 2 


Cross Reference 
Declared Variables 


Name Defined Type Length References 

&ABC 200 *CHAR 10 900 

&MNO 400 *CHAR 10 1100 

&XYZ 300 *CHAR 10 1000 

Defined Labels 

Label Defined References 

ERR Peres 700 
* CPDQ715 30 Label 'ERR ' does not exist. 

ERROR 800 

xe xe * END OF CROSS REFERENCE ** * * % 
5763SS1 V3RIM0 940909 Control Language MYLIB/DUMPERR 05/06/94 11:12:55 Page 3 
Message Summary 
Severity 
Total 0-9 10-19 20-29 30-39 40-49 50-59 60-69 70-79 80-89 90-99 
0 0 


Program DUMPERR not created in library MYLIB. Maximum error severity 30. 
x**x*x*e* END OF MESSAGE SUM 
**x*ee*e END OF COMPILATIO 


Title: 

The program number, release, modification level and date of OS/400. 
2 | The date and time of the compiler run. 

The page number in the listing. 


4 | The parameter values specified, (or defaults if not specified), on the 
CRTBNDCL command. If the source is not in a database file, the member 
name, date, and time are omitted. 


5 | The name of the compiler. 


Source: 
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6 | The sequence numbers of lines (records) in the source. A dash following a 
sequence number indicates that a source statement begins at that sequence 
number. The absence of a dash indicates that a statement is the 
continuation of the previous statement. 


Comments between source statements are handled like any other source 
statement and have sequence numbers. 


The source statements. 


[co ~ 


The last date the source statement was changed or added. If the source is 
not in a database file, or the dates have been reset using RGZPFM, the 
date is omitted. 


9 | If an error is found during compilation and can be traced to a specific 
source statement, the error message is printed immediately following the 
source statement. An asterisk (*) indicates the line contains an error 
message. The line contains the message identifier, severity, and the text of 
the message. 


For more information about compilation errors, see fe ncountered 


Cross-References: 


The symbolic variable table is a cross-reference listing of the variables 
validly declared in the program. The table lists the variable, the sequence 
number of the statement where the variable is declared, the variable’s 
attributes, and the sequence numbers of statements that refer to the 
variable. 


The label table is a cross-reference listing of the labels validly defined in 
the program. The table lists the label, the sequence number of the 
statement where the label is defined, and the sequence numbers of 
statements that refer to the label. 


Messages: 


This section is not included in the sample listing because no general error 
messages were issued for the sample module. If there were general error messages 
for this module, this section would contain, for each message, the message 
identifier, the severity, and the message. 


Message Summary: 


A summary of the number of messages issued during compilation. The 
total number is given along with totals by severity. 


A completion message is printed following the message summary. 
The title, prologue, source, and message summary sections are always printed for 


the *SOURCE option. The cross-reference section is printed if the *XREF option is 
specified. The message section is printed only if general errors are found. 


Errors Encountered during Compilation 


In the compiler listing of a module, an error condition that relates directly to a 
specific command is listed after that command. See ECL Module Compiled 
d for an example of these inline messages. Messages that do not 


relate to a specific command but are more general in nature are listed in a 
messages section of the listing, not inline with source statements. 


58 0S/400 CL Programming V5R2 


The types of errors that are detected at compile time include syntax errors, 
references to variables and labels not defined, and missing statements. The 
following types of errors stop the procedure from being created (severity codes are 
ignored). 

* Value errors 

° Syntax errors 

* Errors related to dependencies between parameters within a command 

* Errors detected during validity checking. 


Even after an error that stops the procedure from being created is encountered, the 
compiler continues to check the source for errors. This lets you see and correct as 
many errors as possible before you try to create the module or program again. 


Obtaining a Procedure Dump 


You can obtain a CL procedure dump during procedure processing. The CL 
procedure dump consists of a listing of all messages on the procedure’s message 
queue and the values of all variables used in the procedure. This information may 
be useful in determining the cause of a problem affecting procedure processing. 


To obtain a CL procedure dump, do one of the following: 


* Run the Dump CL Program (DMPCLPGM) command. This command can only 
be used in a CL procedure and does not end the CL procedure. 


* Enter D in response to inquiry message CPA0701 or CPA0702. The system sends 
this message whenever it receives an unmonitored escape message from a CL 
procedure. If the program is running in an interactive job, the system sends the 
message to the job’s external message queue. If the program is running as a 


batch job, the system sends the message to the system operator message queue, 
OSYSOPR. 


Specify INQMSGRPG(*SYSRPYL) for the job. See the Systems Management 
category of information in the iSeries Information Center for a description of this 
job attribute. The IBM-supplied system reply list specifies a reply of D for 
message CPA0702 or CPA0701. The system will print a dump if it receives one 
of the inquiry messages. 

* Change the default reply for message CPA0701 or CPA0702 from C (cancel 
program) to D (dump procedure). This prints a procedure dump whenever a 
function check occurs in a CL procedure. To change the default, enter the 
following command: 

CHGMSGD MSGID(CPAQ702) MSGF(QCPFMSG) DFT(D) 


Note: The security officer, or another user with update authority to the 
QCPFMSG file, must enter the CHGMSGD command. 


Changing the message default causes a dump to be printed under any of the 
following conditions: 


* The system operator message queue is in default mode and the message is sent 
from a batch job. 


* The display station user presses the Enter key without typing a response, 
causing the message default to be used. 


* INOMSGRPY(*DFT) is specified for the job. 


5763SS1 V3R1MO0 940909 CL Program Dump 5/24/94 11:05:03 EJ Page 1 


Job name. ....... : DSP04 User name... ... =: SMITH Job number ..... . : 01329 
Program name. ..... : DUMP ABR ArYy 2-2 vena dae : MYLIB Statement. ...... : 1200 


Module name ...... : DUMP Procedure name ... : DUMP 
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Time 
110503 
110503 


Variable 


&ABC 
&XYZ 


EON & 


Messages 
Message G Message From To 
ID Sev Type Text Program Inst Program Inst 
cPC2102 00 COMP. Library LARRY created. QLICRLIB *N DUMP. +N 
CPF2110 40 ESC Library MOE not found. QLICLLIB *N DUMP. #N 
Variables 


Type Length Value Value in Hexadecimal 
Feet Hl + 2 + Re sa, a TP abe, aes io irae a, es HE Bees Gee ee! ar teas SP 


*CHAR 10 "ONE p6D5C540404040404040. 
*CHAR 10 ‘TWO : E3E6D640404040404040 


seeee END OF DUMP #4448 
The program number, release, modification level and date of OS/400. 
The date and time the dump was printed. 

The fully qualified name of the job in which the procedure was running. 
The name and library of the program. 


The number of the statement running when the dump was taken. If the 
command is a nested command, the statement number is that of the outer 
command. 


Each message on the call message queue, including the time the message 
was sent, message ID, severity, type, text, sending program and instruction 
number, and receiving program and instruction number. 


All variables declared in the procedure, including variable name, type, 
length, value, and hexadecimal value. 


If a decimal variable contains decimal data that is not valid, the character 
and hexadecimal values are printed as *CHAR variables. 


If the value for the variable cannot be located, *NOT ADDRESSABLE is 
printed. This can occur if the CL procedure is used in a command 
processing program for a command that has a parameter with either 
TYPE(*NULL) or PASSVAL(*NULL) specified, or if RTNVAL(*YES) was 
specified for the parameter and a return variable is not coded on the 
command. 


If a variable is declared as TYPE(*LGL), it is shown on the dump as 
*CHAR with a length of 1. 


Displaying Module Attributes 


You can use the Display Module (DSPMOD) command to display the attributes of 
a module. The information displayed or printed can be used to determine the 


options 


specified on the command used to create the module. 


For more information on this command, see the CL section of the Programming 
category in the iSeries Information Center. 


Displaying Program Attributes 


You can use the Display Program (DSPPGM) command to display the attributes of 
a program. The information displayed or printed can be used to determine the 


options 


specified on the command used to create the program. 


For more information on this command, see the CL section of the Programming 
category in the iSeries Information Center. 


60 05/400 CL Programming V5R2 


Return Code Summary 


The return code (RTNCDE) parameter on the RTVJOBA command is a 5-digit 
decimal value with no decimal positions (12345. for example). The decimal value 
indicates the status of called programs. CL programs do not set the return code. 
However, you can retrieve the current value of the return code as set by another 
program in a CL program. You can do this by using the RTNCDE parameter of the 
RTVJOBA command. 


The following list summarizes the return codes used by languages supported on 
OS/400: 


* RPGIV programs 
The return codes sent by the RPG IV compiler are: 


0 When the program is created 


2 When the program is not created 


The return codes sent by running RPG IV programs are: 


0 When a program is started, or by the CALL operation before a program 
is called 

1 When a program ends with LR set on 

2 When a program ends with an error (response of C, D, F, or S to an 


inquiry message) 


3 When a program ends because of a halt indicator (H1-H9) 


RPG IV return codes are tested only after a CALL: 

— 0 or 1 indicate no error 

— 3 gives an RPG IV status code of 231 

— Any other value gives an RPG IV status code 202 (call ended in error) 


The return code cannot be tested directly by the user in the RPG IV program. 
* ILE COBOL/400® programs 
The return codes sent by running COBOL/400 programs are: 


0 By each CALL statement before a program is called 


2 When a program receives a function check (CPF9999) or the generic I/O 
exception handler gets control and there is no applicable USE procedure 


COBOL/400 programs cannot retrieve these return codes. A return code value of 
2 sends message CBE9001 and runs a Reclaim Resources (RCLRSC) command 
with the *ABNORMAL option. 


* BASIC programs 


Compiled or interpreted BASIC programs can set the return code to any value 
between -32768 and 32767 by coding an expression on the END or STOP 
statements. If no expression is coded, the return codes are set to: 


0 For normal completion 


1 For programs ending because of an error 


BASIC return code values can be retrieved using the CODE intrinsic function. 
* PL/I programs 
The return codes sent by PL/I programs are: 
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For normal completion, set at the beginning of the run unit 
When set by a STOP statement or a call to PLIDUMP with the S option 
When an ERROR condition is raised 


When PL/I detects an error that did not allow the ERROR condition to 
be raised 


PrP WO NY © 


If any other value is found, it is set up by the PLIRETC built-in function or by a 
called procedure. PLIRETC passes a return code from the PL/I program to the 
program that called it, changing the current return code value. 


PL/I programs can retrieve the return code using the PLIRETV built-in function. 
* Pascal programs 
The Pascal compiler sets the following return codes: 


0 For successful compilation 


2 When the program object is not produced 


Pascal does not explicitly set the return code at run time. The user can use the 
ONERROR exception handling routine to monitor for particular exceptions, then 
set the return code using the RETCODE procedure. 


Pascal return codes can be retrieved using the RETVALUE parameter of the 
Pascal SYSTEM procedure. The return code is set to 0 before the SYSTEM call 
and will contain the updated return code when returned. 


* C/400* programs 


The current value of the integer return code returned by the last C/400® return 
statement in a C/400 program. 


Compiling Source Programs for a Previous Release 


The Create Control Language Program (CRTCLPGM) command allows you to 
compile CL source programs to use on a previous release by using the target 
release (TGTRLS) parameter. The TGTRLS parameter specifies on which release of 
the OS/400® licensed program the CL program object created intends to run. You 
can specify *CURRENT, *PRV, or a specific release level. 


ACL program compiled with TGTRLS(*CURRENT) runs only on the current 
release or later releases of the operating system. A CL program compiled with a 
specified TGTRLS value other than *CURRENT can run on the specified release 
value and on later releases. 


Previous-Release (*PRV) Libraries 


The CL compiler retrieves information about previous-release commands and files 
from CL previous-release (*PRV) libraries. Two types of libraries contain 
previous-release support: system libraries and user libraries. The libraries have the 
names QSYSVxRxMx and QUSRVxRxMx. (VxRxMx represents the version, release, 
and modification level of the supported previous release). For example, the 
QUSRV4R5M0 library supports a system that runs Version 4 Release 5 Modification 
level 0 of the OS/400 licensed program. 


When the CL compiler compiles for a supported previous release, it first checks for 
commands and files in the previous-release libraries. When failing to find the 


62 0S/400 CL Programming V5R2 


command or file in the previous-release libraries, the system performs a search of 
the library list (*LIBL) or the qualified library. 


OSYSVxRxMx Libraries: The QSYSVxRxMx libraries install at the same time as the 
CL compiler support for a previous release installs. The QSYSVxRxMx libraries 
include the command definition objects and output files “OUTFILE) that are found 
in library QSYS for that particular previous release. 


QUSRVxRxMx Libraries: You can create your own QUSRVxRxMx libraries to hold 
copies of your commands and files as they existed in the supported previous 
release. This is especially important if the commands or files have changed on the 
current release. 


When the compiler looks for previous-release commands and files, it checks the 
QUSRVxRxMx library (if it exists) before checking the QSYSVxRxMx library. 


Note: Use the QUSRVxRxMx libraries to hold previous-release user commands 
and files, instead of the QSYSVxRxMx libraries. When installing future 
releases of the CL compiler, support for previous releases install as well. 
Once the previous-release support is installed, the QUSRVxRxMx libraries 
for releases that are no longer supported can be deleted. 


Do not add previous-release libraries to the library list (*LIBL). They contain 
commands and files that support earlier releases and cannot run on the current 
system. Only the CL compiler refers to and uses the commands and files in the 
previous-release libraries. The system commands that are supplied for a previous 
release are in the primary language for the system. There are no secondary 
national language versions available. 


See the appropriate CL Reference command, (Save Object (SAVOBJ), Save Changed 
Object (SAVCHGOB)J), or Save Library (SAVLIB)), for how to save objects on a 
different release. 


Note: CL programs that are compiled in the System/38°" environment cannot be 
saved for a previous release. 


Installing CL Compiler Support for a Previous Release 
To install the *PRV CL compiler support and QSYSVxRxMx libraries: 
1. Enter: 
GO LICPGM 


To view the Licensed Program Menu. 
2. Select option 11 (Install licensed programs). 


3. Select the option that is named 5769SS1 IBM Operating System/400® Version 3 
(OS/400) — *PRV CL Compiler Support. This causes the QSYSVxRxMx libraries 
to install. 


If you are not using the CL compiler support for a previous release, you can 
remove this support by entering: 


DLTLICPGM LICPGM(5769SS1) OPTION(9) 
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When the CL compiler support is removed, the QSYSVxRxMx libraries get 
removed from the system, but the QUSRVxRxMx libraries do not. If no need 
exists for the QUSRVxRxMx libraries, you must explicitly delete them using the 
Delete Library (DLTLIB) command. 
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Chapter 3. Controlling Flow and Communicating between 
Programs and Procedures 


You can use the CALL, CALLPRC, and RETURN commands to pass control back 
and forth between programs and procedures. Each command has slightly different 
characteristics. Information may be passed to called programs and procedures as 
parameters when control is passed. 


Special attention should be given to programs created with USRPRF(*OWNER) 
that run CALL or CALLPRC commands. Security characteristics of these 
commands differ when they are processed in programs running under an owner's 


‘icc prohie See theeeee Renae Book (oranioneatiematadionebout 


user profiles. 


This chapter includes General-Use Programming Interfaces (GUPI), made available 
by IBM for use in customer-written programs. 


CALL Command 


The CALL command calls a program named on the command, and passes control 
to it. The CALL command has the following format: 


CALL PGM(library-name/program-name) PARM(parameter-values) 


The program name or library name may be a variable. If the called program is in a 
library that is not on the library list, you must specify the qualified name of the 
program on the PGM parameter. The PARM parameter is discussed under 

ara 2 2 When the called 
meni Gishes running, control returns to the next command in the calling 


program. 

PROGA ; > PROGB 
PGM PGM 
DCL cam DE acica 
CALL PROGB CHGVAR... 


SNDPGMMSG...< 


ENDPGM ENDPGM 
RBAFN555-0 
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The sequence of CALL commands in a set of programs calling each other is the 
call stack. For example, in this series: 


PROGA -——>PROGB -——>PROGC 

CALL PROGB ——— CALL PROGC —4—— 

.< .« 

ENDPGM ENDPGM ENDPGM 
RBAFN556-0 


the call stack is: 


Return Call 
r > PROGA 
—» PROGB _ 
PROGC <— 
RBAFN530-0 


When PROGC finishes processing, control returns to PROGB at the command after 
the call to PROGC. Control is thus returned up the call stack. This occurs whether 
or not PROGC ends with a RETURN or an ENDPGM command. 


ACL program can call itself. 


CALLPRC Command 


The CALLPRC command calls a procedure named on the command, and passes 
control to it. The CALLPRC command has the following format: 


CALLPRC Procedure(procedure-name) PARM(parameter-values) RTNVAL(return-value-variable) 


The procedure name may not be a variable. The PARM parameter is discussed 
under [Pa 2 orams a ac 
the called procedure finishes running, control returns to the next command in the 
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calling procedure. 


PGMA 
PROGA ; > PROGB 
PGM PGM 
DCL... DCL... 
CALLPRC PROGB CHGVAR... 


SNDPGMMSG... < 


ENDPGM ENDPGM 


RBAFN539-0 


The sequence of CALLPRC commands in a set of procedures calling each other is 
the call stack. For example, in this series: 


PGMA SRVPGMA 
PROCA ;——» PROCB > PROCC 
CALLPRC PROCB CALLPRC PROCC 
_< _< 
ENDPGM ENDPGM ENDPGM 
RBAGN540-0 


the call stack is: 


Return Call 


r >| PROGA 


_,) PROGB 


PROGC <— 


RBAFN530-0 


When PROGC finishes processing, control returns to PROGB at the command after 
the call to PROGC. Control is thus returned up the call stack. This occurs whether 
or not PROGC ends with a RETURN or an ENDPGM command. 


A CL procedure can call itself. 
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RETURN Command 


The RETURN command in a CL procedure or OPM program removes that 
procedure or OPM program from the call stack. 


If the procedure containing the RETURN command was called by a CALLPRC 
command, control is returned to the next sequential statement after that CALLPRC 
command in the calling program. 


If a MONMSG command specifies an action that ends with a RETURN command, 
control is returned to the next sequential statement after the statement that called 
the procedure or program containing the MONMSG command. 

The RETURN command has no parameters. 


Note: If you have a RETURN command in an initial program, the command entry 
display is shown. You may wish to avoid this for security reasons. 


Passing Parameters between Programs and Procedures 


When you pass control to another program or procedure, you can also pass 
information to it for modification or use within the receiving program or 
rocedure. See the discussion of this under 
. You can specify the information to be passed on the PARM parawictet on 
the CALL command or the CALLPRC command. The characteristics and 
requirements for these commands are slightly different. 


For instance, if PROGA contains the following command: 
CALL PROGB PARM(&AREA) 


then it calls PROGB and passes the value of AREA to it. PROGB must start with 
the PGM command, which also must specify the parameter it is to receive: 


PGM PARM(&AREA) /* PROGB */ 


For the CALL command or the CALLPRC command, you must specify the 
parameters passed on the PARM parameter, and you must specify them on the 
PARM parameter of the PGM command in the receiving program or procedure. 
Because parameters are passed by position, not name, the position of the value 
passed in the CALL command or the CALLPRC command must be the same as its 
position on the receiving PGM command. For example, if PROGA contains the 
following command: 


CALL PROGB PARM(&A &B &C ABC) 


it passes three variables and a character string, and if PROGB starts with: 
PGM PARM(&C &B &A &D) /*PROGB*/ 


then the value of &A in PROGA is used for &C in PROGB, and so on; &D in 
PROGB is ABC. The order of the DCL statements in PROGB is unimportant. Only 
the order in which the parameters are specified on the PGM statement determines 
what variables are passed. 


In addition to the position of the parameters, you must pay careful attention to 
their length and type. Parameters listed in the receiving procedure or program 
must be declared as the same length and type as they are in the calling procedure 
or program. Decimal constants are always passed with a length of (15 5). 
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When you use the CALLPRC command and pass character string constants, you 
must specify the exact number of bytes, and pass exactly that number. The called 
procedure can use the information in the operational descriptor to determine the 
exact number of bytes passed. You can use the API CEEDOD to access the 
operational descriptor. See the CL section of the Programming category for the 
iSeries Information Center for information on the API CEEDOD. 


When you use the CALL command, character string constants of 32 bytes or less 
are always passed with a length of 32 bytes. If the string is longer than 32, you 
must specify the exact number of bytes, and pass exactly that number. 


The following is an example of a procedure or program that receives the value 
&VARI: 


PGM PARM(&VAR1) /*PGMAx/ 
DCL VAR1 *CHAR LEN(36) 


ENDPGM 


The CALL command or CALLPRC command must specify 36 characters: 
CALLPRC PGMA (ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJ) 


The following example specifies the default lengths: 


PGM PARM(&P1 &P2) 

DCL VAR(&P1) TYPE(*CHAR) LEN(32) 

DCL VAR(&P2) TYPE(*DEC) LEN(15 5) 

IF (&P1 *EQ DATA) THEN(CALL MYPROG &P2) 
ENDPGM 


To call this program, you could specify: 
CALL PROG (DATA 136) 


The character string DATA is passed to &P1; the decimal value 136 is passed to 
&P2 


Referring to locally defined variables incurs less overhead than referring to passed 
variables. Therefore, if the called procedure or program frequently refers to passed 
variables, performance can be improved by copying the passed values into a local 
variable and referring to the locally defined value rather than the passed value. 


When calling an OPM CL program, the number of parameters that are passed to it 
must exactly match the number that is expected by the program. The number that 
is expected is determined at the time the program is created. (The operating 
system prevents you from calling a program with more or fewer parameters than 
the program expects). When calling an ILE program or procedure, the operating 
system does not check the number of parameters that are passed on the call. In 
addition, the space where the operating system stores the parameters is not 
reinitialized between procedure calls. Calling a procedure that expects "n" 
parameters with "n-1" parameters makes the system use whatever is in the 
parameter space to access the "nth" parameter. The results of this action are very 
unpredictable. This also applies to procedures written in other ILE languages that 
call CL procedures or are called by CL procedures. 


This also gives you more flexibility when you write ILE CL procedures, because 
you can write procedures that have variable length parameter lists. For example, 


based on the value of one parameter, a parameter that is specified later in the list 
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may not be required. If the controlling parameter indicated an unspecified optional 
parameter, the called procedure should not attempt to refer to the optional 
parameter. 


You can also specify the special value *OMIT for any parameter that you want to 
omit from the parameter list. If you specify *OMIT for a parameter, the calling 
procedure passes a null pointer. The procedure that is called has to be prepared to 
handle a null pointer if it refers to a parameter that is omitted. In control language 
(CL), you can check for a null pointer by monitoring for MCH3601 on the first 
reference to the omittable parameter. The procedure must take appopriate action if 
it receives a MCH3601. 


The following example has two CL procedures. The first procedure expects one 
parameter; if that parameter remains unspecified, results will be unpredictable. The 
first procedure calls another procedure, PROC1. PROC1 expects one or two 
parameters. If the value of the first parameter is ’1’, it expects the second 
parameter as specified. If the value of the second parameter is ’0’, it assumes that 
the second parameter remained unspecified and used a default value instead. 
PROC1 also uses the CEEDOD API to determine the actual length that is passed 
for the second parameter. 


70 0S/400 CL Programming V5R2 


MAIN: PGM  PARM(&TEXT)/* &TEXT must be specified. Results will be + 
unpredictable if it is omitted.*/ 
DCL VAR(&TEXT) TYPE(*CHAR) LEN(10) 
CALLPRC PRC(PROC1) PARM('0') 
CALLPRC = PRC(PROC1) PARM('1' &TEXT) 
CALLPRC PRC(PROC1) PARM('1' 'Goodbye') 
ENDPGM 


PROC1: PGM PARM(&P1 &P2) /* PROC1 - Procedure with optional + 
parameter &P2 */ 

DCL VAR(&P1) TYPE(*LGL) /*Flag which indicates + 

whether or not &P2 will be specified. If + 
value is '1', then &P2 is specified */ 

DCL VAR(&P2) TYPE(*CHAR) LEN(10) 

DCL VAR(&MSG) TYPE(*CHAR) LEN(10) 

DCL VAR(&PARMPOS) TYPE(*CHAR) LEN(4) /* + 
Parameter position for CEEDOD*/ 

DCL VAR(&PARMDESC) TYPE(*CHAR) LEN(4) /* + 
Parameter description for CEEDOD*/ 

DCL VAR(&PARMTYPE) TYPE(*CHAR) LEN(4) /* + 
Parameter datatype from CEEDOD*/ 

DCL VAR(&PARMINFO1) TYPE(*CHAR) LEN(4) /* + 
Parameter information from CEEDOD */ 

DCL VAR(&PARMINFO2) TYPE(*CHAR) LEN(4) /* + 
Parameter information from CEEDOD */ 

DCL VAR(&PARMLEN) TYPE(*CHAR) LEN(4) /* + 
Parameter length from CEEDOD*/ 

DCL  VAR(&PARMLEND) TYPE(*DEC) LEN(3 0) /* + 
Decimal form of parameter lengthx/ 

IF  COND(&P1) THEN(DO) /* Parm 2 ist 
specified, so use the parm value for the + 
message text*/ 

CHGVAR VAR(%BIN(&PARMPOS 1 4)) VALUE(2) /* Tell + 
CEEDOD that we want the operational + 
descriptor for the second parameter*/ 

CALLPRC PRC(CEEDOD) PARM(&PARMPOS &PARMDESC + 
&PARMTYPE &PARMINFO1 &PARMINFO2 &PARMLEN) + 
/* Call CEEDOD to get the length of data + 
specified for &P2*/ 

CHGVAR VAR(&PARMLEND) VALUE(%BIN(&PARMLEN 1 4)) /* + 
Convert the length returned by CEEDOD to + 
decimal format*/ 

CHGVAR VAR(&MSG) VALUE(%SST(&P2 1 &PARMLEND)) /* + 

Copy the data passed in to a local variablex/ 

ENDO 

ELSE | CMD(CHGVAR VAR(2MSG) VALUE('Hello')) /* Use + 

"Hello" for the message textx/ 
SNDPGMMSG MSG(&MSG) 
ENDPGM 


Using the CALL Command 


When the CALL command is issued by a CL procedure, each parameter value 
passed to the called program can be a character string constant, a numeric 
constant, a logical constant, or a CL variable. A maximum of 40 parameters can be 
passed to the called program. The values of the parameters are passed in the order 
in which they appear on the CALL command, and this must match the order in 
which they appear in the parameter list of the called program. The names of the 
variables passed do not have to be the same as the names on the receiving 
parameter list. The names of the variables receiving the values in the called 
program must be declared to the called program, but the order of the declare 
commands is not important. 
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No association exists between the storage in the called program and the variables 
it receives. Instead, when the calling program passes a variable, the storage for the 
variable is in the program in which it was originally declared. The system passes 
variables by address. When passing a constant, the calling program makes a copy 
of the constant, and passes the address of that copy to the called program. 


The result is that when a variable is passed, the called program can change the 
value of the variable, and the change is reflected in the calling program. The new 
value does not have to be returned to the calling program for later use; it is 
already there. Thus no special coding is needed for a variable that is to be returned 
to the calling program. When a constant is passed, and its value is changed by the 
called program, the changed value is not known to the calling program. Therefore, 
if the calling program calls the same program again, it reinitializes the values of 
constants, but not of variables. 


An exception to the previous description is when the CALL command calls an ILE 
C program. When using the CALL command to call an ILE C program and pass 
character or logical constants, the system adds a null character (x’00’) after the last 
non-blank character. If the constant is a character string that is enclosed in 
apostrophes or a hexadecimal constant, the null character is added after the last 
character that was specified. This preserves the trailing blanks (x ’40’ characters). 
Numeric values are not null-terminated. 


If a CL program might be called using a CALL command that has not been 

compiled (an interactive CALL command or through the SBMJOB command), the 
decimal parameters (*DEC) should be declared with LEN(15 5), and the character 
parameters (*CHAR) should be declared LEN(32) or less in the receiving program. 


A CALL command that is not in a CL procedure or program cannot pass variables 
as arguments. Be careful when specifying the CALL command as a command 
parameter that is defined as TYPE(*CMDSTR). This converts the contents of any 
variables that are specified on the PARM parameter to constants. The command 
(CMD) parameters on the Submit Job (SBMJOB) command, Add Job Schedule 
Entry (ADDJOBSCDE) command, or Change Job Schedule Entry (CHGJOBSCDE) 
command are examples. IBM has provided online information on how to pass 
parameters when using an interactive CALL command. Refer to the description of 
the CALL command in the CL section of the Programming category in the iSeries 
Information Center. 


Parameters can be passed and received as follows: 


* Character string constants of 32 bytes or less are always passed with a length of 
32 bytes (padded on the right with blanks). If a character constant is longer than 
32 bytes, the entire length of the constant is passed. If the parameter is defined 
to contain more than 32 bytes, the CALL command must pass a constant 
containing exactly that number of bytes. Constants longer than 32 characters are 
not padded to the length expected by the receiving program. 


The receiving program can receive less than the number of bytes passed. For 
example, if a program specifies that 4 characters are to be received and ABCDEF is 
passed (padded with blanks in 26 positions), only ABCD are accepted and used by 
the program. 


If the receiving program receives more than the number of bytes passed, the 
results may be unexpected. Numeric values passed as characters must be 
enclosed in apostrophes. 

* Decimal constants are passed in packed form and with a length of LEN(15 5), 
where the value is 15 digits long, of which 5 digits are decimal positions. Thus, 
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if a parameter of 12345 is passed, the receiving program must declare the 
decimal field with a length of LEN(15 5); the parameter is received as 
12345 .00000. 


If you need to pass a numeric constant to a program and the program is 


expecting a value with a length and precision other than 15 5, the constant can 


be coded in hexadecimal format. The following CALL command shows how to 


pass the value 25.5 to a program variable that is declared as LEN(5 2): 
CALL PGMA PARM(X'@2550F') 
* Logical constants are passed with a length of 32 bytes. The logical value 0 or 1 


in the first byte, and the remaining bytes are blank. If a value other than 0 or 1 


is passed to a program that expects a logical value, the results may be 
unexpected. 


is 


* A floating point literal or floating point special value (NAN, *INF, or *NEGINF) 


is passed as a double precision value, which occupies 8 bytes. Although a CL 
program cannot process floating point numbers, it can receive a floating point 
value into a character variable and pass that variable to an HLL program that 
can process floating point values. 


* The system can pass a variable if the call is made from a CL procedure or 
program. In this case the receiving program should declare the field to match 


the variable that is defined in the calling CL procedure or program. For example, 


assume that a CL procedure or program defines a decimal variable that is 


named &CHKNUM as LEN(5 0). Then the receiving program should declare the 


field as packed with 5 digits total, with no decimal positions. When running a 
CALL command in batch mode by using the SBMJOB command in a CL 
procedure or program, the system treats any variables that are passed as 
arguments like constants. 


* If either a decimal constant or a program variable can be passed to the called 
program, the parameter should be defined as LEN(15 5), and any calling 
program must adhere to that definition. If the type, number, order, and length 


of 


the parameters do not match between the calling and receiving programs (other 


than the length exception noted previously for character constants), results 
cannot be predicted. 


* The value *N cannot be used to specify a null value because a null value cannot 


be passed to another program. 


In the following example, program A passes six parameters: one logical constant, 
three variables, one character constant, and one numeric constant. 


PGM /* PROGRAM A x/ 

DCL VAR(&B) TYPE(*CHAR) 

DCL VAR(&C) TYPE(*DEC) LEN(15 5) VALUE(13.529) 

DCL VAR(&D) TYPE(*CHAR) VALUE('1234.56') 

CHGVAR VAR(&B) VALUE (ABCDEF) 

CALL PGM(B) PARM('1' &B &C &D XYZ 2) /* Note blanks between parms «/ 


ENDPGM 


PGM PARM(&A &B &C &W &V &U) /* PROGRAM B x/ 
DCL VAR(&A) TYPE(*LGL) 
DCL VAR(&B) TYPE(*CHAR) LEN(4) 
DCL VAR(&C) TYPE(*DEC) 
/* Default length (15 5) matches DCL LEN in program A */ 
DCL VAR(&W) TYPE(*CHAR) 
DCL VAR(&V) TYPE(*CHAR) 
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DCL VAR(&U) TYPE(*DEC) 


. ENDPGM 


Note: If the fifth parameter passed to PGMB was 456 instead of XYZ and was 
intended as alphanumeric data, the value would have been specified as 
'456' in the parameter. 


The logical constant ’1’ does not have to be declared in the calling program. It is 
declared as type logical and named &A in program B. 


Because no length is specified on the DCL command for &B, the default length, 
which is 32 characters, is passed. Only 6 characters of &B are specified (ABCDEF). 
Because &B is declared with only 4 characters in program B, only those 4 
characters are received. If they are changed in program B, those 4 positions for &B 
will also be changed in program A for the remainder of this call. 


The length (LEN) parameter must be specified for &C in program A. If it were not 
specified, the length would default to the specified value’s length, which would be 
incompatible with the default length expected in program B. &C has a value of 
13.52900. 


&W in program B (&D in program A) is received as a character because it is 
declared as a character. Apostrophes are not necessary to indicate a string if TYPE 
is *CHAR. In program A, the length defaults to the value’s length of 7 (the decimal 
point is considered a position in a character string). Program B expects a length of 
32. The first 7 characters are passed, but the contents past the position 7 cannot be 
predicted. 


The variable &V is a character string XYZ, padded with blanks on the right. The 
variable &U is numeric data, 2.00000. 


IBM has provided online information on the default lengths in the DCL 
commands. Refer to the DCL command in the CL section of the Programming 
category in the iSeries Information Center. 


Common Errors When Calling Programs and Procedures 


The following sections describe the errors encountered most frequently in passing 
values on a CALL command or a CALLPRC command. Some of these errors can 
be very difficult to debug, and some have serious consequences for program 
functions. 


Date Type Errors Using the CALL Command 

The total length of the command string includes the command name, spaces, 
parameter names, parentheses, contents of variables and apostrophes used. For 
most commands, the command string initiates the command processing program 
as expected. However, for some commands some variables a not be ae i as 


expected. For more information on the topic of variables, see 


When the CALL command is used with the CMD parameter on the SBMJOB 
command, unexpected results may occur. Syntactically, the CALL command 
appears the same when used with the CMD parameter as it does when used as the 
compiler directive for the CALL command. When used with the CMD parameter, 
the CALL command is converted to a command string that is run at a later time 
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when the batch subsystem initiates it. When the CALL command is used by itself, 
the CL compiler generates code to perform the call. 


Common problems with decimal constants and character variables often occur. In 
the following cases, the command string is not constructed as needed: 


¢ When decimal numbers are converted to decimal constants. 


When the command string is run, the decimal constant is passed in a packed 
form with a length of LEN(15 5). It is not passed in the form specified by the CL 
variable. 


¢ When a character variable is declared longer than 32 characters. 


The contents of the character variable is passed as described previously, usually as 
a quoted character constant with the trailing blanks removed. As a result, the 
called program may not be passed enough data. 


The following methods can be used to correct errors in constructing command 

strings: 

* Create the CALL command string to be submitted by concatenating the various 
portions of the command together into one CL variable. Submit the command 
string using the request data (RQSDTA) parameter of the SBMJOB command. 


* For CL character variables larger than 32 characters where trailing blanks are 
significant, create a variable that is one character larger than needed and 
substring a non-blank character into the last position. This prevents the 
significant blanks from being truncated. The called program should ignore the 
extra character because it is beyond the length expected. 


* Create a command that will initiate the program to be called. Submit the new 
command instead of using the CALL command. The command definition 
ensures the parameters are passed to the command processing program as 
expected. 


Data Type Errors 

When passing a value, the data type (TYPE parameter) must be the same (*CHAR, 
*DEC, or *LGL) in the calling procedure or program and in the called procedure or 
program. Errors frequently occur in this area when you attempt to pass a numeric 
constant. If the numeric constant is enclosed in apostrophes, it is passed as a 
character string. However, if the constant is not enclosed in apostrophes, it is 
passed as a packed numeric field with LEN(15 5). 


In the following example, a quoted numeric value is passed to a program that 
expects a decimal value. A decimal data error (escape message MCH1202) occurs 
when variable &A is referred to in the called program (PGMA): 

CALL PGMA PARM('123') /* CALLING PROGRAM »/ 


PGM PARM(&A) = /* PGMA */ 
DCL 8A *DEC LEN(15 5) /* DEFAULT LENGTH */ 


IF (&A *GT 0) THEN(...) /* MCH1202 OCCURS HERE */ 


In the following example, a decimal value is passed to a program defining a 
character variable. Generally, this error does not cause run-time failures, but 
incorrect results are common: 


CALL PGMB PARM(12345678) /* CALLING PROG */ 


PGM PARM(&A) /* PGMB */ 
DCL &A *CHAR 8 
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ENDPGM 
Variable &A in PGMB has a value of hex 001234567800000F. 


Generally, data can be passed from a logical (*LGL) variable to a character 
(*CHAR) variable, and vice versa, without error, so long as the value is expressed 
as ’0’ or ’1’. 


Decimal Length and Precision Errors 

If a decimal value is passed with an incorrect decimal length and precision (either 
too long or too short), a decimal data error (MCH1202) occurs when the variable is 
referred to. In the following examples, the numeric constant is passed as LEN(15 
5), but is declared in the called procedure or program as LEN(5 2). Numeric 
constants are always passed as packed decimal (15 5). 


CALL PGMA PARM(123) /* CALLING PROG */ 


PGM PARM(&A) /* PGMA */ 
DCL &A *DEC (5 2) 


IF (&A *GT @) THEN(...) /* MCH1202 OCCURS HERE */ 


If a decimal variable had been declared with LEN(5 2) in the calling program or 
procedure and the value had been passed as a variable instead of as a constant, no 
error would occur. 


If you need to pass a numeric constant to a procedure or program and the 
procedure or program is expecting a value with a length and precision other than 
15 5, the constant can be coded in hexadecimal format. The following CALL 
command shows how to pass the value 25.5 to a program variable that is declared 
as LEN(5 2): 


CALL PGMA PARM(X'02550F') 


If a decimal value is passed with the correct length but with the wrong precision 
(number of decimal positions), the receiving procedure or program interprets the 
value incorrectly. In the following example, the numeric constant value (with 
length (15 5)) passed to the procedure is handled as 25124.00. 


CALL PGMA PARM(25.124) /* CALLING PGM */ 


PGM PARM(&A) /* PGMA */ 
DCL 8A *DEC (15 2) /* LEN SHOULD BE 15 5*/ 
ENDPGM 


These errors occur when the variable is first referred to, not when it is passed or 
declared. In the next example, the called program does not refer to the variable, 
but instead simply places a value (of the detected wrong length) in the variable 
returned to the calling program. The error is not detected until the variable is 
returned to the calling program and first referred to. This kind of error can be 
especially difficult to detect. 

PGM /* PGMA */ 


DCL &A *DEC (7 2) 
CALL PGMB PARM(&A) /* (7 2) PASSED TO PGMB */ 
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IF (8A *NE 0) THEN(...) /* *MCH1202 OCCURS HERE */ 


ENDPGM 


PGM PARM(&A) /* PGMB */ 

DCL &A *DEC (5 2) /* WRONG LENGTH / 
“CHGVAR &A (&B-&C) /* VALUE PLACED in &A */ 
RETURN 


When control returns to program PGMA and &A is referred to, the error occurs. 


Character Length Errors 

If you pass a character value longer than the declared character length of the 
receiving variable, the receiving procedure or program cannot access the excess 
length. In the following example, PGMB changes the variable that is passed to it to 
blanks. Because the variable is declared with LEN(5), only 5 characters are changed 
to blanks in PGMB, but the remaining characters are still part of the value when 
referred to in PGMA. 

PGM /* PGMA */ 

DCL &A *CHAR 10 

CHGVAR &A 'ABCDEFGHIJ' 

CALL PGMB PARM(8&A) /* PASS to PGMB */ 


IF (8A *EQ ' ') THEN(...) /* THIS TEST FAILS */ 
ENDPGM 


PGM PARM(&A) /* PGMB */ 

DCL &A *CHAR 5 /* THIS LEN ERROR*/ 

CHGVAR 8A ' ' /* 5 POSITIONS ONLY; OTHERS UNAFFECTED */ 
RETURN 


While this kind of error does not cause an escape message, variables handled this 
way may function differently than expected. 


If the value passed to a procedure or program is shorter than its declared length in 
the receiving procedure or program, there may be more serious consequences. In 
this case, the value of the variable in the called procedure or program consists of 
its values as originally passed, and whatever follows that value in storage, up to 
the length declared in the called procedure or program. The content of this 
adopted storage cannot be predicted. If the passed value is a variable, it could be 
followed by other variables or by internal control structures for the procedure or 
program. If the passed value is a constant, it could be followed in storage by other 
constants passed on the CALL or CALLPRC command or by internal control 
structures. 


If the receiving procedure or program changes the value, it operates on the original 
value and on the adopted storage. The immediate effect of this could be to change 
other variables or constants, or to change internal structures in such a way that the 
procedure or program fails. Changes to the adopted storage take effect 
immediately. 


In the following example, two 3-character constants are passed to the called 
program. Character constants are passed with a minimum of 32 characters for the 
CALL command. (Normally, the value is passed as 3 characters left-adjusted with 
trailing blanks.) If the receiving program declares the receiving variable to be 
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longer than 32 positions the extra positions use adopted storage of unknown value. 
For this example, assume that the two constants are adjacent in storage. 


CALL PGMA ('ABC' 'DEF') /* PASSING PROG */ 


PGM PARM(&A &B) /* PGMA */ 

DCL &A *CHAR 50 /* VALUE:ABC+29' '+DEF+15! ' */ 
DCL &B *CHAR 10 /* VALUE:DEF+7' ' */ 

CHGVAR VAR(&A) (' ') /* THIS ALSO BLANKS &B */ 


ENDPGM 
Values passed as variables behave in exactly the same way. 


In the following example, two 3-character constants are passed to the called 
procedure. Only the number of characters specified are passed for the CALLPRC 
command. If the receiving program declares the receiving variable to be longer 
than the length of the passed constant, the extra positions use adopted storage of 
unknown value. 


In the following example, assume the two constants are adjacent in storage. 
CALLPRC PRCA ('ABC' 'DEF') /* PASSING PROG */ 


PGM PARM(&A &B) /* *PRCA x/ 

DCL &A *CHAR 5 /*  VALUE:'ABC' + 'DE! */ 

DCL &B *CHAR 3 /* VALUE:'DEF' */ 

CHGVAR 8A | ' /* This also blanks the first two bytes of &B */ 
ENDPGM 


Using Data Queues to Communicate between Programs and 
Procedures 


Data queues are a type of system object that you can create, to which one HLL 
procedure or program can send data, and from which another HLL procedure or 
program can receive data. The receiving program can be already waiting for the 
data, or can receive the data later. 


The advantages of using data queues are: 


* Using data queues frees a job from performing some work. If the job is an 
interactive job, this can provide better response time and decrease the size of the 
interactive program and its process access group (PAG). This, in turn, can help 
overall system performance. For example, if several work station users enter a 
transaction that involves updating and adding to several files, the system can 
perform better if the interactive jobs submit the request for the transaction to a 
single batch processing job. 


* Data queues are the fastest means of asynchronous communication between two 
jobs. Using a data queue to send and receive data requires less overhead than 
using database files, message queues, or data areas to send and receive data. 

* You can send to, receive from, and retrieve a description of a data queue in any 
HLL procedure or program by calling the QQNNDDTAQ, QRCVDTAQ, 
QMHRDOM, QCLRDTAQ, and QMHORDOD programs without exiting the 
HLL procedure or program or calling a CL procedure or program to send, 
receive, clear, or retrieve the description. 
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* When receiving data from a data queue, you can set a time out such that the job 
waits until an entry arrives on the data queue. This differs from using the 
EOFDLY parameter on the OVRDBF command, which causes the job to be 
activated whenever the delay time ends. 


* More than one job can receive data from the same data queue. This has an 
advantage in certain applications where the number of entries to be processed is 
greater than one job can handle within the desired performance restraints. For 
example, if several printers are available to print orders, several interactive jobs 
could send requests to a single data queue. A separate job for each printer could 
receive from the data queue, either in first-in-first-out (FIFO), last-in-first-out 
(LIFO), or in keyed-queue order. 


* Data queues have the ability to attach a sender ID to each message being placed 
on the queue. The sender ID, an attribute of the data queue which is established 
when the queue is created, contains the qualified job name and current user 
profile. 


In addition to these advantages, you can journal your data queues. This allows you 
to recover the object to a consistent state, even if the object was in the middle of 
some change action when the abnormal initial program load (IPL) or crash 
occurred. Journaling also provides for replication of the data queue journal to a 
remote system (using remote journal for instance). This lets the system reproduce 
the actions in a similar environment to replicate the application work. For more 
information about journaling support on the iSeries server, see the 

article in the Information Center. 


The following is an example showing how data queues work. Several jobs place 
entries on a data queue. The entries are handled by a server job. This might be 
used to have jobs send processed orders to a single job that would do the printing. 
Any number of jobs can send to the same queue. 


Sending Job 1———> 


Sending Job 2——_» DTAQ |+—-»Server Job 


Sending Job 3——_> 
RBAFN535-0 

Another example using data queues follows. A primary job gets the work requests 

and sends the entries to a data queue (by calling the QSNDDTAQ program). The 

server jobs receive the entries from the data queue (by calling the QRCVDTAQ 

program) and process the data. The server jobs can report status back to the 

primary job using another data queue. 


Data queues allow the primary job to route the work to the server jobs. This frees 
the primary job to receive the next work request. Any number of server jobs can 
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receive from the same data queue. 


Master Job Master Queues Server Jobs 

Work INPUT 
CALL QSNDDTAQ }—> L—» Job 1 
t—> Job 2 
i—> Job 3 

STATUS 
CALL QRCVDTAQ «— L—» Job 1 

Results 

+<__ DTAQ +> Job 2 
i—> Job 3 
RBAFN536-0 


When no entries are on a data queue, server jobs have the following options: 
* Wait until an entry is placed on the queue 


* Wait for a specific period of time; if the entry still has not arrived, then continue 
processing 


* Do not wait, return immediately. 


Data queues can also be used when a program needs to wait for input from 
display files, ICF files, and data queues at the same time. When you specify the 
DTAQ parameter for the following commands: 


* Create Display File (CRTDSPF) command 

* Change Display File (CHGDSPF) command 

* Override Display File (OQVRDSPF) command 

* Create ICF File (CRTICFF) command 

* Change ICF File (CHGICFF) command 

* Override ICF File (OVRICFF) command 

you can indicate a data queue that will have entries placed on it when any of the 
following happens: 


* An enabled command key or Enter key is pressed from an invited display 
device 


¢ Data becomes available from an invited ICF session 


Support is available to optionally associate a data queue to an output queue by 
using the Create Output Queue (CRTOUTQ) or Change Output Queue 
(CHGOUTQ) command. The system logs entries in the data queue when spooled 
files are in ready (RDY) status on the output queue. A user program can determine 
when a spooled file is available on an output queue by using the Receive Data 
Queue (QRCVDTAQ) API to receive information from a data queue. See the CL 


section of the Programming category of the iSeries Information Center for details 
about eke ota Oe Oto rand Por inote nictica con 


about data queues on output queues see the | 
book. 


Jobs running on the system can also place entries on the same data queue as the 
one specified in the DTAQ parameter by using the QSNDDTAQ program. 
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An application calls the QRCVDTAQ program to receive each entry placed on the 

data queue and then processes the entry based on whether it was placed there by a 

display file, an ICF file, or the QOONNDDTAQ eram. For more information, see 
q D 


Remote Data Queues 


You can access remote data queues with Distributed Data Management (DDM) 
files. DDM files make it possible for a program residing on one server to access a 
data queue on a remote server to perform any of the following functions: 


* send data to a data queue 
* receive data from a data queue 
* clear data from a data queue 


An application program that currently uses a standard data queue can also access 
a remote DDM data queue without changing or compiling the application again. 
To ensure the correct data queue is accessed, you may need to do one of the 
following: 


* Delete the standard data queue and create a DDM data queue that has the same 
name as the original standard data queue. 


* Rename the standard data queue. 


You can create a DDM data queue with the following command: 


CRTDTAQ DTAQ(LOCALLIB/DDMDTAQ) TYPE(*DDM) 
RMTDTAQ(REMOTELIB/REMOTEDTAQ) RMTLOCNAME (SYSTEMB) 
TEXT('DDM data queue to access data queue on SYSTEMB') 


You can also use an expansion of the previous example ("Master Job/Server Job”) 
to create a DDM data queue to use with remote data queues. The master job 
resides on SystemA; the data queues and server jobs are moved to SystemB. After 
creating two DDM data queues (INPUT and STATUS), the master job continues to 
communicate asynchronously with the server jobs that reside on SystemB. The 
following example shows how to create a DDM data queue with remote data 
queues: 

CRTDTAQ DTAQ(LOCALLIB/INPUT) TYPE(*DDM) 


RMTDTAQ(REMOTELIB/INPUT) RMTLOCNAME (SystemB) 
TEXT('DDM data queue to access INPUT on SYSTEMB') 


CRTDTAQ DTAQ(LOCALLIB/STATUS) TYPE(*DDM) 
RMTDTAQ(REMOTELIB/STATUS) RMTLOCNAME(SystemB) 
TEXT('DDM data queue to access STATUS on SYSTEMB') 


The master job calls QSNDDTAQ, then passes the data queue name of 
LOCALLIB/INPUT and sends the data to the remote data queue 
(REMOTELIB/INPUT) on SystemB. To receive data from the remote data queue, 
(REMOTELIB/STATUS), the master job passes the data queue name of 
LOCALLIB/STATUS for the call to QRCVDTAQ. 


See the CL section of the Programming category in the iSeries Information Center 
for more information on DDM data queues. 


Chapter 3. Controlling Flow and Communicating between Programs and Procedures 81 


SystemA SystemB 
Master Job 
we INPUT 
i—p Jobl 
CALL QSNDDTAQ > Job? 
r——> Job3 
STATUS 
i—» Jobl 
CALL QRCVDTAQ > Job? 
Results Job3 
RBAFN538-0 


Figure 1. Example of Accessing a Remote Data Queue 


Comparisons with Using Database Files as Queues 


The following describes the differences between using data queues and database 
files: 


Data queues have been improved to communicate between active procedures 
and programs, not to store large volumes of data or large numbers of entries. 
For these purposes, use database files as queues. 


Data queues should not be used for long-term storage of data. For this purpose, 
you should use database files. 


When using data queues, you should include abnormal end routines in your 
programs to recover any entries not yet completely processed before the system 
is ended. 


It is good practice to periodically (such as once a day) delete and re-create a 
data queue at a safe point. Performance can be affected if too many entries exist 
without being removed. Re-creating the data queue periodically will return the 
data queue to its optimal size. 


Similarities to Message Queues 


Data queues are similar to message queues, in that procedures and programs can 
send data to the queue that is received later by another procedure or program. 

However, more than one program can have a receive pending on a data queue at 
the same time, while only one program can have a receive pending on a message 
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queue at the same time. (Only one program receives an entry from a data queue, 
even if more than one program is waiting.) Entries on a data queue are handled in 
either first-in-first-out, last-in-first-out, or keyed-queue order. When an entry is 
received, it is removed from the data queue. 


Prerequisites for Using Data Queues 


Before using a data queue, you must first create it using the Create Data Queue 
(CRTDTAQ) command. The following is an example: 


CRTDTAQ DTAQ(MYLIB/INPUT) MAXLEN(128) 
TEXT('Sample data queue') 


The required MAXLEN parameter specifies the maximum length (1 to 64,512 
characters) of the entries that are sent to the data queue. 


Managing the Storage Used by a Data Queue 


Each entry receives a storage allocation when sent to a data queue. The storage 
allocated will be the value that is specified for the maximum entry length of the 
data queue that was specified on the Create Data Queue (CRTDTAQ) command. 
When receiving an entry from a data queue, the data queue removes the entry, but 
it does not free the auxiliary storage. The system uses the auxiliary storage again 
when sending a new entry to the data queue. The queue grows larger when not 
receiving entries that are sent to the queue. Performance is better by maintaining 
the size of the queue to less than 100 entries. If a data queue has grown too large, 
delete the data queue by using the Delete Data Queue (DLTDTAQ) command. On 
completion of the data queue deletion, re-create the queue by using the Create 
Data Queue (CRTDTAQ) command. 


There is another way to manage the size of a data queue on Release V4R5MO and 
beyond. This consists of using the SIZE and AUTORCL keywords on the 
CRTDTAQ command. You can use the SIZE keyword to specify the maximum 
number of entries and the initial number of entries for the data queue. You can use 
the AUTORCL keyword to indicate if the data queue should have storage 
automatically reclaimed when the queue is empty. Specifying *YES for AUTORCL 
and allocating additional storage to the queue allows for automatic storage 
allocation when the queue is empty. The amount of storage allocated equals the 
initial number of entries specified for the queue. If AUTORCL contains a value of 
*NO, which is the default, the system does not automatically reclaim storage from 
unused space. To reclaim the storage the data queue uses, you would need to 
delete and re-create it as described in the preceding paragraph. 


Allocating Data Queues 


If your application requires that a data queue is not accessed by more than one job 
at a time, it should be coded to include an Allocate Object (ALCOBJ) command 
before using a data queue. The data queue should then be deallocated using the 
Deallocate Object (DLCOBJ) command when the application is finished using it. 


The ALCOBJ command does not, by itself, restrict another job from sending or 
receiving data from a data queue or clearing a data queue. However, if all 
applications are coded to include the ALCOBJ command before any use of a data 
queue, the allocation of a data queue already allocated to another job will fail, 
preventing the data queue from use by more than one job at a time. 


When an allocation fails because the data queue is already allocated to another job, 
the system issues an error message, CPF1002. The Monitor Message (MONMSG) 
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command can be used in the application procedure to monitor for this message 
and respond to the error message. Possible responses include sending a message to 
the user and attempting to allocate the data queue again. See 

4 for more information. 


Examples Using a Data Queue 


The following examples explain three methods to process data queue files. 


Example 1: Waiting up to 2 Hours to Receive Data from Data 
Queue 

In the following example, program B specifies to wait up to 2 hours (7200 seconds) 
to receive an entry from the data queue. Program A sends an entry to data queue 
DTAQ1 in library QGPL. If program A sends an entry within 2 hours, program B 
receives the entries from this data queue. Processing begins immediately. If 2 hours 
elapse without procedure A sending an entry, program B processes the time-out 
condition because the field length returned is 0. Program B continues receiving 
entries until this time-out condition occurs. The programs are written in CL; 
however, either program could be written in any high-level language. 


The data queue is created with the following command: 
CRTDTAQ DTAQ(QGPL/DTAQ1) MAXLEN(80) 


In this example, all data queue entries are 80 bytes long. 


In program A, the following statements relate to the data queue: 


PGM 
DCL &FLDLEN *DEC LEN(5 0) VALUE(80) 
DCL &FIELD *CHAR LEN(80) 


.(determine data to be sent to the queue) 


CALL QSNDDTAQ PARM(DTAQ1 QGPL &FLDLEN &FIELD) 


In program B, the following statements relate to the data queue: 


PGM 

DCL &FLDLEN *DEC LEN(5 0) VALUE(80) 

DCL &FIELD »*CHAR LEN(8Q) 

DCL &WAIT *DEC LEN(5 0) VALUE(7200) /* 2 hours */ 


LOOP: CALL QRCVDTAQ PARM(DTAQ1 QGPL &FLDLEN &FIELD &WAIT) 
IF (&FLDLEN *NE 0) DO /* Entry received */ 


. (process data from data queue) 


GOTO LOOP = /* Get next entry from data queue */ 
ENDDO 


. (no entries received for 2 hours; process time-out condition) 


Example 2: Waiting for Input from a Display File and an ICF File 
The following example is different from the usual use of data queues because there 
is only one job. The data queue serves as a communications object within the job 
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rather than between two jobs. 


JobA 
ICF \, » Application Display 
File Program File 
ee Data << 
Queue 


RBAFN544-0 


In this example, a program is waiting for input from a display file and an ICF file. 
Instead of alternately waiting for one and then the other, a data queue is used to 
allow the program to wait on one object (the data queue). The program calls 
QRCVDTAQ and waits for an entry to be placed on the data queue that was 
specified on the display file and the ICF file. Both files specify the same data 
queue. Two types of entries are put on the queue by display data management and 
ICF data management support when the data is available from either file. ICF file 
entries start with *ICFF and display file entries start with *DSPF. 


The display file or ICF file entry that is put on the data queue is 80 characters in 
length and contains the field attributes described in the following list. Therefore, 
the data queue that is specified using the CRTDSPF, CHGDSPF, OVRDSPF, 
CRTICFEF, CHGICFF, and OVRICFF commands must have a length of at least 80 
characters. 


Position (and Data Type) 
Description 


1 through 10 (character) 
The type of file that placed the entry on the data queue. This field will 
have one of two values: 
*ICFF for ICF file 
*DSPF for display file 


If the job receiving the data from the data queue has only one display file 
or one ICF file open, then this is the only field needed to determine what 
type of entry has been received from the data queue. 


11 through 12 (binary) 
The unique identifier for the file. The value of the identifier is the same as 
the value in the open feedback area for the file. This field should be used 
by the program receiving the entry from the data queue only if there is 
more than one file with the same name placing entries on the data queue. 


13 through 22 (character) 
The name of the display file or ICF file. This is the name of the file actually 
opened, after all overrides have been processed, and is the same as the file 
name found in the open feedback area for the file. This field should be 
used by the program receiving the entry from the data queue only if there 
is more than one display file or ICF file that is placing entries on the data 
queue. 


23 through 32 (character) 
The library where the file is located. This is the name of the library, after 
all overrides have been processed, and is the same as the library name 
found in the open feedback area for the file. This field should be used by 
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the program receiving the entry from the data queue only if there is more 
than one display file or ICF file that is placing entries on the data queue. 


33 through 42 (character) 
The program device name, after all overrides have been processed. This 
name is the same as that found in the program device definition list of the 
open feedback area. For file type *DSPF, this is the name of the display 
device where the command or Enter key was pressed. For file type *ICFF, 
this is the name of the program device where data is available. This field 
should be used by the program receiving the entry from the data queue 
only if the file that placed the entry on the data queue has more than one 
device or session invited prior to receiving the data queue entry. 


43 through 80 (character) 
Reserved. 


The following example shows coding logic that the program previously described 
might use: 


OPEN DSPFILE ... /* Open the Display file. DTAQ parameter specified on*/ 


/* CRTDSPF, CHGDSPF, or OVRDSPF for the file. */ 
OPEN ICFFILE ... /* Open the ICF file. DTAQ parameter specified on */ 
/* CRTICFF, CHGICFF, or OVRICFF for the file. */ 

DO 
WRITE DSPFILE /* Write with Invite for the Display file */ 
WRITE ICFFILE /* Write with Invite for the ICF file x/ 
CALL QRCVDTAQ /* Receive an entry from the data queue specified */ 
/* on the DTAQ parameters for the files. Entries x/ 
/* are placed on the data queue when the data is x/ 
/* available from any invited device or session */ 
/* on either file. */ 


/* After the entry is received, determine which file */ 
/* has data available, read the data, process it, */ 
/* invite the file again and return to process the */ 


/* next entry on the data queue. */ 
IF 'ENTRY TYPE' FIELD = '*DSPF ' THEN /* Entry is from display «/ 
DO /* file. Since this entry*/ 


/* does not contain the */ 
/* data received, the datax/ 
/* must be read from the */ 
/* file before it can be */ 


READ DATA FROM DISPLAY FILE /* processed. */ 
PROCESS INPUT DATA FROM DISPLAY FILE 
WRITE TO DISPLAY FILE /* Write with Invite */ 
END 
ELSE /* Entry is from ICF */ 


/* file. Since this entryx/ 
/* does not contain the */ 
/* data received, the data*/ 
/* must be read from the */ 
/* file before it can be */ 
/* processed. x/ 

READ DATA FROM ICF FILE 

PROCESS INPUT DATA FROM ICF FILE 

WRITE TO ICF FILE /* Write with Invite */ 

LOOP BACK TO RECEIVE ENTRY FROM DATA QUEUE 
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END 
Example 3: Waiting for Input from a Display File and a Data 
Queue 
In the following example, the program in Job B is waiting for input from a display 
file that it is using and for input to arrive on the data queue from Job A. Instead of 
alternately waiting for the display file and then the data queue, the program waits 
for one object, the data queue. 


Job A Job B 


Batch Job Interactive Job Using 
Placing User Entries Data Queue Display File and 

on the Receiving Entries 
Data Queue from the Data Queue 


Display File 
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The program calls QRCVDTAQ and waits for the placement of an entry on the 
data queue that was specified on the display file. Job A is also placing entries on 
the same data queue. There are two types of entries that are put on this queue, the 
display file entry, and the user-defined entry. Display data management places the 
display file entry on the data queue when data is available from the display file. 
Job A places the user-defined entry on the data queue. 


The structure of the display file entry is described in the previous example. 


The structure of the entry placed on the queue by Job A is defined by the 
application programmer. 


The following example shows coding logic that the application program in Job B 
might use: 


OPEN DSPFILE ... /* Open the Display file. DTAQ parameter specified on*/ 


/* CRTDSPF, CHGDSPF, or OVRDSPF for the file. */ 
DO 
WRITE DSPFILE /* Write with Invite for the Display file */ 
CALL QRCVDTAQ /* Receive an entry from the data queue specified */ 
/* on the DTAQ parameter for the file. Entries x/ 
/* are placed on the data queue either by Job A or */ 
/* by display data management when data is x/ 
/* available from any invited device on the display */ 
/* file. x/ 


/* After the entry is received, determine what type */ 
/* of entry it is, process it, and return to receive */ 
/* the next entry on the data queue. x/ 
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IF 'ENTRY TYPE' FIELD = '*DSPF ' THEN /* Entry is from display «/ 
DO /x file. Since this entry~/ 
/* does not contain the */ 

/* data received, the datax/ 

/* must be read from the */ 

/* file before it can be */ 


READ DATA FROM DISPLAY FILE /* processed. */ 
PROCESS INPUT DATA FROM DISPLAY FILE 
WRITE TO DISPLAY FILE /* Write with Invite */ 
END 
ELSE /* Entry is from Job A. */ 


/* This entry contains */ 
/* the data from Job A, */ 
/* so no read is required*/ 
/* before processing the */ 
/* data. */ 
PROCESS DATA QUEUE ENTRY FROM JOB A 
LOOP BACK TO RECEIVE ENTRY FROM DATA QUEUE 


END 


Creating Data Queues Associated with an Output Queue 


You can associate a data queue with an output queue. When a spooled file on the 
output queue goes to a READY status, the entry that is defined below is sent to 
the data queue. Use the Create Data Queue (CRTDTAQ) command to create the 
data queue. Specify the maximum message length (MAXLEN) parameter value as 
at least 128. The sequence (SEQ) parameter value should be *FIFO or *LIFO. 


Sample Data Queue Entry 


Position and (data type) 
Description 


1 through 10 (character) 
Function - Identifies the funtion that created the data queue entry. The 
value for a spooled file is *SPOOL. 


11 through 20 (character) 
Record type - Identifies the record type within the function. Valid values 
are: 


01 The output queue received a spooled file that is in READY status. 


21 through 38 (character) 
Qualified job name - Identifies the qualified job name of the job that 
created the spooled file that is placed on the output queue. 


CHAR(10) 
Job name 


CHAR(10) 
User name 


CHAR(6) 
Job number 


39 through 48 (character) 
Spooled file name - Identifies the name of the spooled file that is placed on 
the output queue. 
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49 through 52 (binary) 
Spooled file number - Identifies the number of the spooled file that is 
placed on the output queue. 


53 through 72 (character) 
Qualified output queue name - Identifies the qualified name of the output 
queue on which the spooled file was placed. 


CHAR(10) 
Output queue name 


CHAR(10) 
Library of the output queue 


73 through 128 (character) 
Reserved 


Using Data Areas to Communicate between Procedures and Programs 


A data area is an object used to hold data for access by any job running on the 
system. A data area can be used whenever you need to store information of limited 
size, independent of the existence of procedures or files. Typical uses of data areas 
are: 


* To provide an area (perhaps within each job’s QTEMP library) to pass 
information within a job. 


* To provide a field that is easily and frequently changed to control references 
within a job, such as: 


— Supplying the next order number to be assigned 
— Supplying the next check number 
— Supplying the next save/restore media volume to be used 


* To provide a constant field for use in several jobs, such as a tax rate or 
distribution list. 


* To provide limited access to a larger process that requires the data area. A data 
area can be locked to a single user, thus preventing other users from processing 
at the same time. 


To create a data area other than a local or group data area, use the Create Data 
Area (CRTDTAARA) command. By doing this, you create a separate object in a 
specific library, and you can initialize it to a value. To use the value in a CL 
procedure or program, use a Retrieve Data Area (RTVDTAARA) command to bring 
the current value into a variable in your procedure or program. If you change this 
value in your CL procedure or program and want to return the new value to the 
data area, use the Change Data Area (CHGDTAARA) command. 


To display the current value, use the Display Data Area (DSPDTAARA) command. 
You can delete a data area using the Delete Data Area (DLTDTAARA) command. 


You can journal your data areas. This allows you to recover the object to a 
consistent state, even if the object was in the middle of some change action when 
the abnormal IPL or crash occurred. Journaling also provides for replication of the 
data area journal to a remote system (using remote journal for instance). This lets 
the system reproduce the actions in a similar environment to replicate the 
application work. For more information about journaling support on iSeries 
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Local Data Area 


A local data area is created for each job in the system, including autostart jobs, jobs 
started on the system by a reader, and subsystem monitor jobs. 


The system creates a local data area, which is initially filled with blanks, with a 
length of 1024 and type *CHAR. When you submit a job using the SEMJOB 
command, the value of the submitting job’s local data area is copied into the 
submitted job’s local data area. You can refer to your job’s local data area by 
specifying *LDA for the DITAARA keyword on the CHGDTAARA, RTVDTAARA, 
and DSPDTAARA commands or *LDA for the substring built-in function (%SST). 


The following is true of a local data area: 

* The local data area cannot be referred to from any other job. 

¢ You cannot create, delete, or allocate a local data area. 

* No library is associated with the local data area. 

* You cannot change the local data area in a secondary thread. 

* The ILE CL compiler generates code to ensure that a procedure running in a 


secondary thread cannot access the local data area while a procedure running in 
the initial thread is changing it. 


The local data area contents exist across routing step boundaries. Therefore, using 
a Transfer Job (TFRJOB), Transfer Batch Job (TFRBCHJOB), Reroute Job (RRTJOB), 
or Return (RETURN) command does not affect the contents of the local data area. 


You can use the local data area to: 
* Pass information to a procedure or program without the use of a parameter list. 


* Pass information to a submitted job by loading your information into the local 
data area and submitting the job. Then, you can access the data from within 
your submitted job. 


* Improve performance over other types of data area accesses from a CL 
procedure or program. 


* Store information without the overhead of creating and deleting a data area 
yourself. 


Most high-level languages can also use the local data area. The SBMxxxJOB and 
STRxxxRDR commands cause jobs to start with a local data area initialized to 
blanks. Only the SBMJOB command allows the contents of the submitting job’s 
local data area to be passed to the new job. 


Group Data Area 


The system creates a group data area when an interactive job becomes a group job 
(using the Change Group Attributes [CHGGRPA] command). Only one group data 
area can exist for a group. The group data area is deleted when the last job in the 
group is ended (with the ENDJOB, SIGNOFF, or ENDGRPJOB command, or with 
an abnormal end), or when the job is no longer part of the group job (using the 
CHGGRPA command with GRPJOB(*NONE) specified). 


A group data area, which is initially filled with blanks, has a length of 512 and 
type *CHAR. You can use a group data area from within a group job by specifying 
*GDA for the DITAARA parameter on the CHGDTAARA, RTVDTAARA, and 
DSPDTAARA commands. A group data area is accessible to all of the jobs in the 


group. 
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The following are true for a group data area: 

* You cannot use the group data area as a substitute for a character variable on 
the substring built-in function (%SUBSTRING or %SST). (You can, however, 
move a 512-byte character variable used by the substring function into or out of 
the group data area.) 

* A group data area cannot be referred to by jobs outside the group. 

* You cannot create, delete, or allocate a group data area. 

* No library is associated with a group data area. 


The contents of a group data area are unchanged by the Transfer to Group Job 
(TFRGRPJOB) command. 


In addition to using the group data area as you use other data areas, you can use 
the group data area to communicate information between group jobs in the same 
group. For example, after issuing the Change Group Job Attributes (CHGGRPA) 
command, the following command can be used to set the value of the group data 
area: 


CHGDTAARA DTAARA(*GDA) VALUE('January1988') 


This command can be run from a program or can be issued by the work station 
user. 


Any other CL procedure or program in the group can retrieve the value of the 
group data area with the following CL command: 


RTVDTAARA DTAARA(*GDA) RTNVAR(&GRPARA) 


This command places the value of the group data area (January1988) into CL 
variable &GRPARA. 


Program Initialization Parameter (PIP) Data Area 
A PIP data area (PDA) is created for each prestart job when the job is started. The 
object sub-type of the PDA is different than a regular data area. The PDA can only 
be referred to by the special value name *PDA. The size of the PDA is 2000 bytes 
but the number of parameters contained in it is not restricted. 


The RTVDTAARA, CHGDTAARA, and DSPDTAARA CL commands and the 
RIVDTAARA and CHGDTAARA macro instructions support the special value 
*PDA for the data area name parameter. 


Remote Data Areas 


You can access remote data areas by using Distributed Data Management (DDM). 

You do not need to change or recompile an application program that resides on 

one server when it retrieves data that resides on a remote server. To ensure that 

you are accessing the correct data area, you may need to do one of the following: 

* Delete the standard data area and create a DDM data area that has the same 
name as the original standard data area 


* Rename the standard data area 


You can create a DDM data area by doing the following: 


CRTDTAARA DTAARA(LOCALLIB/DDMDTAARA) TYPE(*DDM) 
RMTDTAARA(REMOTELIB/RMTDTAARA) RMTLOCNAME (SYSTEMB) 
TEXT('DDM data area to access data area on SYSTEMB') 
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To use a value from a data area on a remote server in a CL program, use the 
Retrieve Data Area (RTVDTAARA) command. Specify the name of a DDM data 
area to bring the current value into a variable in your program. If you change this 
value in your CL program and want to return the new value to the remote data 
area, use the Change Data Area (CHGDTAARA) command and specify the same 
DDM data area. 


If you specify the name of a DDM data area when using the Display Data Area 
(DSPDTAARA) command, the value of the DDM data area is displayed, rather 
than the value of the remote data area. You can delete a DDM data area using the 
Delete Data Area (DLTDTAARA) command. 


See the CL section of the Programming category in the iSeries Information Center 
for more information on DDM data areas. 


Creating a Data Area 


Unlike variables, data areas are objects and must be created before they can be 
used. A data area can be created as: 


* A character string that can be as long as 2000 characters. 


* A decimal value with different attributes, depending on whether it is used only 
in a CL program or procedure or also with other high-level language programs 
or procedures. For CL procedures and programs, the data area can have as many 
as 15 digits to the left of the decimal point and as many as 9 digits to the right, 
but only 15 digits total. For other languages, the data area can have as many as 
15 digits to the left of the decimal point and as many as 9 to the right, for a total 
of up to 24 digits. 


* A logical value ’0’ or ‘1’, where ’0’ can mean off, false, or no; and ‘1’ can mean 
on, true, or yes. 


When you create a data area, you can also specify an initial value for the data area. 
If you do not specify one, the following is assumed: 


* O for decimal. 
¢ Blanks for character. 
* 0’ for logical. 


To create a data area, use the Create Data Area (CRTDTAARA) command. In the 
following example, a data area is created to pass a customer number from one 
program to another: 


CRTDTAARA DTAARA(CUST) TYPE(*DEC) + 
LEN(5 ©) TEXT('Next customer number') 


Data Area Locking and Allocation 


The CHGDTAARA command uses a *SHRUPD (shared for update) lock on the 
data area during command processing. The RT'VDTAARA and DSPDTAARA 
commands use a *“SHRRD (shared for read) lock on the data area during command 
processing. If you are performing more than one operation on a data area, you 
may want to use the Allocate Object (ALCOBJ) command to prevent other users 
from accessing the data area until your operations are completed. For example, if 
the data area contains a value that is read and incremented by jobs running at the 
same time, the ALCOBJ command _can be used to protect the value in both the 
read and update operations. See for how to allocate objects. 
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For information on handling data areas in other (non-CL) languages, refer to the 
appropriate HLL reference manual. 


Displaying a Data Area 


You can display the attributes (name, library, type, length, data area text 
description), and the value of a data area. See the CL section of the Programming 
category in the iSeries Information Center for a detailed description of the 
Display Data Area (DSPDTAARA) command. 


The display uses the 24-digit format with leading zeros suppressed. 


Changing a Data Area 


The Change Data Area (CHGDTAARA) command changes all or part of the value 
of a specified data area. It does not change any other attributes of the data area. 
The new value can be a constant or a CL variable. If the command is in a CL 
procedure, the data area does not need to exist when the program is created. 


Retrieving a Data Area 


The Retrieve Data Area (RTVDTAARA) command retrieves all or part of a 
specified data area and copies it into a CL variable. The data area does not need to 
exist at compilation time, and the CL variable need not have the same name as the 
data area. Note that this command retrieves, but does not alter, the contents of the 
specified data area. 


Retrieve Data Area Examples 


Example 1 
Assume that you are using a data area named ORDINFO to track the status of an 
order file. This data area is designed so that: 


* Position 1 contains an O (open), a P (processing), or a C (complete). 
* Position 2 contains an I (in-stock) or an O (out-of-stock). 
* Positions 3 through 5 contain the initials of the order clerk. 


You would declare these fields in your procedure as follows: 


DCL VAR(&ORDSTAT) TYPE(*CHAR) LEN(1) 
DCL VAR(&STOCKC) TYPE(*CHAR) LEN(1) 
DCL VAR(&CLERK) TYPE(*CHAR) LEN(3) 


To retrieve the order status into &€ORDSTAT, you would enter the following: 
RTVDTAARA DTAARA(ORDINFO (1 1)) RTNVAR(&ORDSTAT) 


To retrieve the stock condition into &STOCK, you would enter the following: 
RTVDTAARA DTAARA(ORDINFO (2 1)) RTNVAR(&STOCKC) 


To retrieve the clerk’s initials into &CLERK, you would enter the following: 
RTVDTAARA DTAARA(ORDINFO (3 3)) RTNVAR(&CLERK) 


Each use of the RT'VDTAARA command requires the data area to be accessed. If 
you are retrieving many subfields, it is more efficient to retrieve the entire data 
area into a variable, then use the substring built-in function to extract the subfields. 


Example 2 


The following example of the RTVDTAARA command places the specified contents 
of a 5-character data area into a 3-character variable. This example: 
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* Creates a 5-character data area named DAI (in library MYLIB) with the initial 
value of 'ABCDE' 


* Declares a 3-character variable named &CLVAR1 
* Copies the contents of the last three positions of DA1 into &CLVAR1 


To do this, the following commands would be entered: 
CRTDTAARA DTAARA(MYLIB/DA1) TYPE(*CHAR) LEN(5) VALUE(ABCDE) 


DCL VAR(&CLVAR1) TYPE(*CHAR) LEN(3) 
RTVDTAARA DTAARA(MYLIB/DA1 (3 3)) RTNVAR(&CLVARL) 


&CLVAR1 now contains 'CDE'. 


Example 3 
The following example of the RTVDTAARA command places the contents of a 
5-digit decimal data area into a 5-digit decimal digit variable. This example: 


* Creates a 5-digit data area named DA2 (in library MYLIB) with two decimal 
positions and the initial value of 12.39 


* Declares a 5-digit variable named &CLVAR2 with one decimal position 
* Copies the contents of DA2 into &CLVAR2 


To do this, the following commands would be entered: 
CRTDTAARA DTAARA(MYLIB/DA2) TYPE(*DEC) LEN(5 2) VALUE(12.39) 


DCL VAR(&CLVAR2) TYPE(*DEC) LEN(5 1) 
RTVDTAARA DTAARA(MYLIB/DA2) RTNVAR(&CLVAR2) 


&CLVAR2 now contains 0012.3 (fractional truncation occurred). 


Changing and Retrieving a Data Area Example 


The following is an example of using the CHGDTAARA and RTVDTAARA 
commands for character substring operations. 


This example: 


* Creates a 10-character data area named DAI (in library MYLIB) with initial 
value ABCD56781J 


¢ Declares a 5-character variable named &CLVARI1 


* Changes the contents of data area DA1 (starting at position 5 for length 4) to the 
value EFG padding after the G with 1 blank) 


* Retrieves the contents of data area DA1 (starting at position 5 for length 5) into 
the CL variable &CLVAR1 


To do this, the following commands would be entered: 
DCL VAR(&CLVAR1) TYPE(*CHAR) LEN(5) 


CRTDTAARA DTAARA(MYLIB/DA1) TYPE(*CHAR) LEN(10) + 
VALUE ('ABCD56781J') 


CHGDTAARA DTAARA((MYLIB/DA1) (5 4)) VALUE('EFG') 
RTVDTAARA DTAARA((MYLIB/DA1) (5 5)) RTNVAR(&CLVAR1) 
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The variable &CLVAR1 now contains 'EFG I'. 
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Chapter 4. Objects and Libraries 


Objects are the basic units on which commands perform operations. For example, 
programs and files are objects. Through objects you can find, maintain, and process 
your data on the iSeries server. You need only know what object and what 
function (command) you want to use; you do not need to know the storage 
address of your data to use it. 


Note: Objects can reside in both libraries and directories. (Previously, an object 
could reside only in a library.) This chapter contains information only about 
objects residing in libraries. See the Integrated File System topics in the 
Database and File Systems category of information of the iSeries 
Information Center for information on directories. 


This chapter includes General-Use Programming Interface and Associated 
Guidance Information. 


Object Types and Common Attributes 


Each type of object on the server has a unique purpose within the system and has 
an associated set of commands which process that type of object. IBM provides 
online information that contains a complete list of the types of objects, the 
abbreviations used as parameter values for object type parameters, and the 
definition of the object belonging to that type. Refer to the CL section of the 
Programming category in the iSeries Information Center. 


Each object type has a set of common attributes that describes the object. These 
common attributes are listed in [able 2 on page 118) The online help information 
for the Display Object Description (DSPOBJD) display describes these attributes. 


Functions Performed on Objects 


Many functions can be performed on objects. Some functions the system performs 
automatically and others you request through commands. 


Functions the System Performs Automatically 


The functions performed automatically ensure that objects are processed in a 
consistent, secure, and proper way. These functions are: 


* Object type verification. The system checks the type of object and the type of 
function being performed on the object to verify that function can be performed 
on that type of object. For example, if the object specified in a CALL command 
is not a program, the call function cannot be performed. 


* Object authority verification. The system checks the object, the function, and the 
user to verify that user can perform that function on that object. For example, if 
USERA is not authorized to use OBJB in any way, he cannot request that any 
functions be performed on it. 


* Object lock enforcement. The system ensures that the integrity of objects is 
preserved when two or more users try to use an object at the same time. 
Simultaneous changes to an object are locked out; users cannot use an object 
while it is being changed. 
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* Object damage detection and notification. The system monitors for errors during 
the processing of objects and communicates to you unplanned failures that result 
from the unrecognizable contents of objects. These failures are communicated to 
you through standard messages that indicate object damage. The system is 
designed so that these failures are rare, and monitoring and communicating 
these failures provide integrity. 


Functions You Can Perform Using Commands 


The functions you can request through commands are of two types: 


* Specific functions for each object type. For example, create, change, and display 
are specific functions. The specific functions are described in other sections of 
this manual that describe the object type. 


* Some common functions that apply to objects in general are explained in this 
guide: 


Table 1. Common Functions for Objects 


Function 


Searching for multiple objects or a single object in a library 


Specifying authority for objects in a library 


Placing objects in libraries 


Describing objects 


Displaying object descriptions 


Retrieving object descriptions 


Detecting unused objects on the system 


Moving objects between libraries 


Creating duplicate objects 


Renaming objects 


Deleting objects 


Allocating and deallocating objects 


Displaying the lock states on objects 
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Checking for object existence 


Libraries 


On the iSeries server, objects are grouped in special objects called libraries. Objects 
are found using libraries. To access an object in a library, you must be authorized 


and 
information. 


If you specify a library name in the same parameter as the object name, the object 
name is called a qualified name. 


When a library is created you can specify into which user Auxiliary storage pool 
(ASP) the library should be created. A library can be created into a basic user ASP 
or an Independent ASP. See the independent ASPd article for details about the 
independent ASPs. All objects created into the library are created into the same 
ASP as the library. 
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If you are entering a command in which you must specify a qualified name, for 
example, the object name could be: 


DISTLIB/ORDO40C 
The order entry program ORD040C is in the library DISTLIB. 


If you are using prompting during command entry and you are prompted for a 
qualified name, you receive prompts for both the object name and the library 
name. On most commands, you can specify a particular library name, specify 
*CURLIB (the current library for the job), or use a library list. Library lists are 
described in the following section. 


Library Lists 


For commands in which a qualified name can be specified, you can omit specifying 
the library name. If you do so, either of the following happens: 


* For a create command, the object is created and placed in the user’s current 
library, *CURLIB, or in a system library, depending on the object type. For 
example, programs are created and placed in *CURLIB; authorization lists are 
created and placed in the system library, QSYS. 


* For commands other than a create command, the system normally uses a library 
list to find the object. 


Library lists used by OS/400 consist of the following four parts. 


System part 
The system part of the library list contains objects needed by the system. 


Product libraries 
Two product libraries may be included in the library list. The system uses 
product libraries to support languages and utilities that are dependent on 
libraries other than QSYS to process their commands. 


User commands and menus can also specify a product library on the 
PRDLIB parameter on the Create Command (CRTCMD) and Create Menu 
(CRIMNU) commands to ensure that dependent objects can be found. 


The product libraries are managed by the system, which automatically 
places product libraries (such as QRPG) into the reserved product library 
position in the library list when needed. A product library may be a 
duplicate of the current library or of a library in the user part of the library 
list. 


For example, assume that there is a product library in the library list when 
a command or menu that has a product library starts. The system will 
replace the product library in the library list with the new product library 
until the new command ends or the user leaves the new menu. 


Current library 
The current library can be, but does not have to be, a duplicate of any 
library in the library list. The value *CURLIB (current library) may be used 
on most commands as a library name to represent whatever library has 
been specified as the current library for the job. If no current library exists 
in the library list and *CURLIB is specified as the library, QGPL is used. 
You can change the current library for a job by using the Change Current 
Library (CHGCURLIB) or Change Library List (CHGLIBL) command. 


User part 
The user part of the library list contains those libraries referred to by the 
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system’s users and applications. The user part, and the product and 
current libraries, may be different for each job on the system. There is a 
limit of 250 libraries. 


The following diagram shows an example of the structure of the library list: 


Sesh eeneee QSYS System Part 

QSYS2 
QUSRSYS 
QHLPSYS 
QPDA Product Library 1 
QRPG Product Library 2 
OELIB Current Library 
OELIB User Part 
QGPL 

, QTEMP 

RBAFN557-0 


Note: The system places library QPDA in product library 1 when the source entry 
utility (SEU) is used. When SEU is being used to syntax check source code, 
a second product library can be added to product library 2. For example, if 
you are syntax checking RPG source, then QPDA is product library 1 and 
ORPG is product library 2. In most other system functions, product library 2 
is not used. 


Using a library list simplifies finding objects on the system. Each job has a library 
list associated with it. When a library list is used to find an object, each library in 
the list is searched in the order of its occurrence in the list until an object of the 
specified name and type is found. If two or more objects of the same type and 
name exist in the list, you get the object from the library that appears first in the 
library list. The following diagram shows the searches made for an object both 
when the library list (*LIBL) is used and when a library name is specified: 


Note: Alternatively, use *NLVLIBL instead of *LIBL to qualify any command. Enter 
the command from a CL program, on a command line, or anywhere you 
normally enter a command. The system uses *NLVLIBL to determine which 
libraries to search for the *CMD object. You search only the national 
language support libraries in the library list by specifying *NLVLIBL. 


For more information on signing and verification of “CMD objects, see the 
onl article in the Security category of 
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information of the iSeries Information Center. 


FILE (ORDHDRP) QSYS 
Library List 
QSYS > 
QGPL 
QTEMP 
QGPL 
DISTLIB t-—— 
DSTTESTLB _ 
QTEMP 
pp 
DISTLIB 
Lg ee 
The system searches the ORDHDRP 
libraries in their order | ———— 
of occurrence in the 
library list until the 
first file ORDHDRP is 
found. DSTTESTLB 
ORDHDRP 


r—File (DISTLIB/ORDHDRP) 


The system searches the 
library DISTLIB for the file 
ORDHDRP. The library DISTLIB 
does not have to be in the 
library list for the job. 


RBAFN525-0 


The following diagram shows what happens when two objects of the same name 
but different types are in the library list. The system will search for CUSTINQ 
*PILE in the library list by specifying: 
DSPOBJD OBJ(*LIBL/CUSTINQ) OBJTYPE(*FILE) 
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Library List iano 
QSYS ee <n 
QGPL 
QTEMP 

QGPL 
DISTLIB —— 
DSTTESTLB | eee 
QTEMP 
sp ee 
DISTLIB 
————> CUSTINQ 
(*PGM) 
The system searches 
the libraries in their 


order of occurrence in 
the library list until DSTTESTLB 
an object of the same 
name and type is CUSTINQ 
found. The object in (* FILE) 
DISTLIB with the name ° 
CUSTINQ is bypassed 
because the object 
type is not *FILE. 


RBAFN541-0 


Generally, a library list is more flexible and easier to use than qualified names. 
More important than the advantage of not entering the library name, is the 
advantage of performing functions in an application on different data simply by 
using a different library list without having to change the application. For example, 
a CL program PGMA updates a data area CHKNBR. If the library name is not 
specified, the program can update the data area named CHKNBR in different 
libraries depending on the use of the library list. For example, assume that JOBA 
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and JOBB both call PGMA as shown in the following illustration: 


JOBA Libraries JOB B 
PGMA QSYS PGMA 
DTAARA oS DTAARA 
(CHKNBR) (CHKNBR) 
QGPL 
Library List QTEMP Library List 
QSYS ee QSYS 
QGPL _— QGPL 
QTEMP QTEMP 
DISTLIBI1 DISTLIB1 DISTLIB2 
——> CHKNBR 
DISTLIB2 
CHKNBR 
RBAFN526-0 


However, the use of a qualified name is advantageous in any of the following 
situations: 


* When the object you are using is not in the library list for the job 


* When there is more than one object of the same name in the library list and you 
want one in a specific library 


* When you want to ensure that a specific library is used for security reasons. 


If, however, you call a program using a qualified name and the program attempts 
to open files whose names are not qualified, the files are not opened if they are not 
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in the library list, as shown in the following example: 


JOB A Libraries 
CALL DISTLIB2/PGMA —— QSYS 
FILE a 
(ORDENTP) 
QGPL 
Library List QTEMP 
QSYS — 
QGPL — 
QTEMP 
DISTLIBI DISTLIB1 
DISTLIB2 
5} PGMA 
ORDENTP 
RBAFN527-0 


The call to PGMA is successful because the program name is qualified on the 
CALL command. However, when the program attempts to open file ORDENTP, the 
open operation fails because the file is not in one of the libraries in the library list, 
and its name is not qualified. If library DISTLIB2 was added to the library list or a 
qualified file name was used, the program could open the file. Some high-level 
languages do not allow a qualified file name to be specified. By using an Override 
(OVRxxx) command, a qualified name can be specified. 


A Job’s Library List 

Each job’s library list consists of up to four parts: a system part, a user part, and 
the current and product libraries. Only the system part will always be included in 
the library list. 


When the system is shipped, the system value QSYSLIBL contains the names of the 
libraries to become the system part of the library list. The shipped values are 
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QSYS, OSYS2, QHLPSYS, and QUSRSYS. The system value QUSRLIBL contains the 
names of the libraries to become the user part of the library list. 


QSYSLIBL can contain 15 library names, and QUSRLIBL can contain 250 library 
names. To change the system portion of a job’s library list, use the Change System 
Library List (CHGSYSLIBL) command. ‘To change the value of either QSYSLIBL or 
QUSRLIBL, use the Change System Value (CHGSYSVAL) command. A change to 
these system values takes effect on new jobs that are started after the system 
values are changed. 


Changing the Library List 

For a running job, you can add entries to or remove entries from the library list by 
using the Add Library List Entry (ADDLIBLE) command or the Remove Library 
List Entry (RMVLIBLE) command, or you can change the libraries in the library 
list by using the CHGLIBL command or the EDTLIBL command. These commands 
change the user part of the library list, not the system part. 


The current library may be added or changed using the Change Current Library 
(CHGCURLIB) or CHGLIBL command. The current library can also be changed in 
the user’s user profile, at sign-on, or on the Submit Job (SBMJOB) command. The 
product libraries cannot be added using a CL command; these libraries are added 
by the system when a command or menu using them is run. The product libraries 
cannot be changed with a CL command; however, they can be changed with the 
Change Library List (QLICHGLL) API. 


When you use these commands, the change to the library list affects only the job in 
which the command is run, and the change is effective only as long as the job is 
running, or until you change the job’s library list again. When the library list is 
changed through the use of these commands, the libraries must exist when the 
command is run. A library cannot be deleted if it exists on an active user’s library 
list. 


When a job is started, the user portion of the library list is determined by the 
values contained in the job description or by values specified on the SBMJOB 
command. A value of *SYSVAL can be specified, which causes the libraries 
specified by the system value QUSRLIBL to become the user portion of the library 
list. If you have specified library names in both the job description and the Batch 
Job (BCHJOB) or SBMJOB command, the library names specified in the BCHJOB or 
SBMJOB command override both the libraries specified in the job description and 
the system value QUSRLIBL. 


The following shows the order in which the user part of the library list specified in 

QUSRLIBL is overridden by commands for individual jobs: 

* A library list can be specified in the job description that, when the job is run, 
overrides the library list specified in QUSRLIBL. (See the Work Management topic 
of the Systems Management category in the iSeries Information Center for more 
information on job descriptions.) 

* When a job is submitted either through a BCHJOB command or a SBMJOB 
command, a library list can be specified on the command. This list overrides the 
library list specified in the job description or in the system value QUSRLIBL. 

* When a job is submitted using the SEMJOB command, *CURRENT (the default) 
can be specified for the library list. *CURRENT indicates that the library list of 
the job issuing the SBMJOB command is used. 

* Within a job, an ADDLIBLE, RMVLIBLE, or CHGLIBL command can be used. 
These commands override any previous library list specifications. 
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* The current library for the job can be changed using the CHGCURLIB or 
CHGLIBL command. 


Instead of entering the CHGLIBL command each time you want to change the 
library list, you can place the command in a CL program: 
PGM /* SETLIBL - Set library list */ 


CHGLIBL LIBL(APPDEVLIB QGPL QTEMP) 
ENDPGM 


If you normally work with this library list, you could set up an initial program to 
establish the library list instead of calling the program each time: 

PGM /* Initial program for QPGMR */ 

CHGLIBL LIBL(APPDEVLIB QGPL QTEMP) 


TFRCTL PGM(QPGMMENU) 
ENDPGM 


This program must be created and the user profile to which it will apply changed 
to specify the new initial program. Control then transfers from this program to the 
QPGMMENU program, which displays the Programmer Menu. 


If you occasionally need to add a library to the library list specified in your initial 
program, you can use the ADDLIBLE command to add that library to the library 
list. For example, the following command adds the library JONES to the end of the 
library list: 


ADDLIBLE LIB(JONES) POSITION(*LAST) 


If part of your job requires a different library list, you can write a CL program that 
saves the current library list and later restores it, such as the following program. 
PGM 
DCL &LIBL *CHAR 2750 
DCL &CMD *CHAR 2760 
(1) RTVJOBA USRLIBL(&LIBL) 
(2)  CHGLIBL (QGPL QTEMP) 


(3) CHGVAR &CMD ('CHGLIBL (' *CAT &LIBL *TCAT ')') 
(4) CALL QCMDEXC (&CMD 2760) 


ENDPGM 


(1) Command to save the library list. The library list is stored into variable 
&LIBL. Each library name occupies 10 bytes (padded on the right with 
blanks if necessary), and one blank is between each library name. 


(2) This command changes the library list as required by the following 
function. 


(3) The Change Variable (CHGVAR) command builds a CHGLIBL command 
in variable CMD. 


(4) QCMDEXC is called to process the command string in variable &CMD. 
The CHGVAR command is required before the call to QCMDEXC because 
concatenation cannot be done on the CALL command. 


Considerations for Setting Up a Library List 


You should consider the following when setting up a library list and using it: 
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* The libraries in a library list must exist on the system. The system values 
QSYSLIBL and QUSRLIBL are accessed when OS/400 is started. If a library in 
either of these values does not exist on the system, a message is sent to the 
system operator’s message queue (QSYSOPR), the library is ignored, and 
OS/400 is started without the library. Once OS/400 is started, no libraries in the 
library list of any active job can be deleted. If any library in the library list 
specified in the job description or in a Batch Job (BCHJOB) or Submit Job 
(SBMJOB) command does not exist or is not available, the job is not started. 


* The libraries in a library list must be authorized to all users who need to use 
them. To initialize a library list (for example, in a Submit Job [SBMJOB], Job 
[JOB], or Create Job Description [CRTJOBD] command), a user must have object 
operational authority for the libraries or the job is not started. A user must also 
have *USE authority to libraries added to the library list using the Add Library 
List Entry (ADDLIBLE) or Change Library List (CHGLIBL) command. 


* When a program running under an adopted user profile adds a library to the 
library list that the current user is not authorized to and does not remove the 
library from the library list before ending the program, the user keeps (*USE 
authority) access to the library after the program exits. This only occurs when 
*LIBL is specified to access the objects. 


* System performance is better when the library list is kept as short as possible. 


Displaying a Library List 
You can use the Display Library List (DSPLIBL) command to display the library 
list for a job currently running. The display contains a list of all the libraries in the 
library list in the same order that they appear in the library list. 


You can also display the library list for an active job using the Display Job 
(DSPJOB) command and selecting option 13 from the Display Job menu. 


Using Generic Object Names 


Sometimes you may want to search for more than one object (even though only 
one might be found) when the object names start with the same characters. This 
type of search is called a generic search and can be used on several commands. 


To use a generic search, specify a generic name in place of the object name on the 
command. A generic name consists of a set of characters common to all the object 
names that identifies a group of objects and ends with an * (asterisk). All objects 
whose names begin with the specified characters and to which you are authorized 
have the requested function performed on them. For example, if you entered the 
Display Object Description (DSPOBJD) command using the generic name ORD*, 
object descriptions for the objects beginning with ORD are shown. 


A generic search can be limited by the following library qualifiers on the generic 

name (the library name parameter value is given in parentheses, if applicable): 

* A specified library. The operation you requested is performed on the generically 
named objects in the specified library only. 

* The library list for the job (*LIBL). The libraries are searched in the order they 
are listed in the library list. The operation you requested is performed on the 
generically named objects in the libraries specified in the library list for the job. 

* The current library for the job (*CURLIB). The current library for the job is 
searched. If no current library exists, QGPL is used. 

* All libraries in the user part of the library list for the job (*USRLIBL). The 
libraries are searched in the order they are listed in the library list, including the 
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current library (*CURLIB). The operation you requested is performed on the 
generically named objects in the libraries specified in the user portion of the 
library list for the job. 

* All user libraries for which you are authorized (*ALLUSR) and the following 
libraries that begin with the letter Q are searched: 


QDSNX QRCL QUSRBRM QUSRPOSGS 
QGPL QRCLXxxxx QUSRDIRCL QUSRPOSSA 
QGPL38 Qsys2 QUSRDIRDB QUSRPYMSVR 
QMPGDATA  QSYS2xxxxx  QUSRIJS QUSRRDARS 
QMQMDATA —-QS36F QUSRINFSKR — QUSRSYS 
QMQMPROC —- QUSER38 QUSRNOTES QUSRVI 
QPFRDATA  QUSRADSM QUSROND QUSRVXRxMx 


Note: 'xxxxx' is the number of a primary auxiliary storage pool (ASP). 
VxRxMx is version, release, and modification level of the library. 


The libraries are searched in alphanumeric order. The following 5/36 
environment libraries that begin with # are not searched with *ALLUSR 
specified: #CGULIB, #COBLIB, #DFULIB, #DSULIB, #RPGLIB, #SDALIB, and 
#SEULIB. The operation you requested is performed on the generically named 
objects in all the user libraries for which you are authorized. 


* All libraries on the system for which you are authorized (*ALL). The libraries 
are searched in alphanumeric order. The operation you requested is performed 
on the generically named objects in all the libraries on the system for which you 
are authorized. 


IBM provides information on operations that use generic functions. Refer to the CL 
section of the Programming category in the iSeries Information Center. 


Searching for Multiple Objects or a Single Object 


In all commands for which you can specify a generic name, you can specify an 
object name (no asterisk is specified) and you can search for multiple objects. If 
you specify an object name and *ALL or *ALLUSR for the library name, the system 
searches for multiple objects, and the search returns objects of the indicated name 
and type for which you are authorized. If you specify a generic name, or if you 
specify *ALL, *ALLUSR, or a library with an object name, you can specify all 
supported object types (or *ALL object types). 


Using Libraries 


A library is an object used to group related objects and to find objects by name. 
Thus, a library is a directory to a group of objects. 


You can use libraries to: 


* Group certain objects for individual users. This helps you manage the objects on 
your system. For example, you might place all the files that a user JOE can use 
in a library JOELIB. 


* Group all objects used for an individual application. For example, you might 
place all your order entry files and programs into an order entry library 
DISTLIB. You need only add one library to the library list to ensure that all your 
order entry files and programs are in the list. This is advantageous if you do not 
want to specify a library name every time you use an order entry file or 
program. 


* Ensure security. For example, you can specify which users have authority to use 
the library and what they are allowed to do with the library. 
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* Simplify security by having automatic authorization list and public authority 
assignment for newly created objects based on the CRTAUT parameter value of 
the library. Auditing attributes for newly created objects can be set based on the 
Create Object Auditing (CRTOBJAUD) parameter value. 


* Simplify save/restore operations by grouping objects that are saved and restored 
at the same time into the same library. You can use a Save Library (SAVLIB) 
command instead of saving objects individually using the Save Object (SAVOBJ) 
command. 


* Use multiple libraries for testing. Refer to [Debugging OPM Programd for more 


information. 


* Use multiple production libraries. For example, you can use one production 
library for source files and for the creation of objects, one for the application 
programs and files, one for objects that are infrequently saved, and one for 
objects that are frequently saved. 


Multiple libraries make it easier to use objects. For example, you can have two files 
with the same name but in different libraries so that one can be used for testing 
and the other for normal processing. As long as you do not specify the library 
name in your program, the file name in the program does not have to be changed 
for testing or normal processing. You control which library is used by using the 
library list. (Objects of the same type can have the same names only if they are in 
different libraries.) 


The two types of libraries are production and test. A production library is for 
normal processing. In debug mode, you can protect database files in production 


libraries from being updated. While in debug mode, any files in test libraries can 
be updated without any unique specifications. (See [chugging OPM Programd for 


more information on using test libraries.) 


Creating a Library 


To create a library, use the Create Library (CRTLIB) command. For example, the 
following CRTLIB command creates a library to be used to contain order entry files 
and programs. The library is named DISTLIB and is a production library. The 
default authority given to the public prevents a user from accessing the library. 
Any object created into the library is given the default public authority of 
*CHANGE based on the CRTAUT value. 


CRTLIB LIB(DISTLIB) TYPE(*PROD) CRTAUT(*CHANGE) CRTOBJAUD(*USRPRF) + 
ASP(1) ASPDEV(*ASP) AUT(*EXCLUDE) TEXT('Distribution library’) 


You should not create a library with a name that begins with the letter Q. During a 
generic search, the system assumes that most libraries with names that begin with 
the letter Q (such_ as QRPG or QPDA) are system libraries. See [ising Generid 

a 07 for more information. 


Specifying Authority for Libraries 


The following describes each of the authorities that can be given to users for 


libraries. See the Beaniy Raed book for more information. 


Object Authority 
Object operational authority for a library gives the user authority to display the 
description of a library. 


Object management authority for a library includes authority to: 
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* Grant and revoke authority. You can only grant and revoke authorities that you 
have. Only the object owner or a user with *ALLOBJ authority can grant object 
management authority for a library. 


* Rename the library. 


Object existence authority and use authority gives the user authority to delete a 
library. 


Object existence authority and object operational authority gives the user 
authority to transfer ownership of the library. 


Data Authority 
Add authority and read authority for a library allows a user to create a new object 
in the library or to move an object into the library. 


Update authority and execute authority for a library allow a user to change the 
name of an object in the library, provided the user is also authorized to the object. 


Delete authority allows the user to remove entries from an object. Delete authority 
for a library does not allow a user to delete objects in the library. Authority for the 
object in the library is used to determine if the object can be deleted. 


Execute authority allows the user to search the library for an object. 


Combined Authority 
*USE authority for a library (consisting of object operational authority, read 
authority, and execute authority) includes authority to: 


* Use a library to find an object 

* Display library contents 

* Place a library in the library list 

* Save a library (if sufficient authority to the object) 


* Delete objects from the library (if the user is authorized to the object in the 
library) 


*CHANGE authority for a library (consisting of object operational authority and 
all data authorities to the library) includes authority to: 


* Use a library to find an object 

* Display library contents 

* Place a library in the library list 

* Save a library (if sufficient authority to the object) 


* Delete objects from the library (if the user is authorized to the object in the 
library) 


* Add objects to the library. 

*ALL authority provides all object authorities and data authorities. The user can 
delete the library, specify the security for the library, change the library, and 
display the library’s description and contents. 


*EXCLUDE authority prevents users from accessing an object. 


To display the authority associated with your library, you may use the Display 
Object Authority (DSPOBJAUT) command. 
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Security Considerations for Objects 


When the system accesses an object that you refer to, it checks to determine if you 

are authorized to use the object and to use it in the way you are requesting. 

Generally, you must be authorized at two levels: 

* You must be authorized to use the object on which you have requested a 
function to be performed. 


* You must be authorized to the library containing the object. If a library list is 
used, you must be authorized to the libraries in the list. 


Object authority is controlled by the system’s security functions, which include the 

following: 

* An object owner and users with *ALLOBJ special authority have all authority for 
an object, and can grant and revoke authority to and from other users. 


* Users have public authority when private authority has not been granted to 
them for the object. 
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be granted for an object and what authority a user needs to perform a function on 
that object. Authority that can be granted for libraries is discussed under 
pe ne A no O bra 


Special considerations apply when writing a program that must be secure (for 
example, a program that adopts the security officer’s user profile). See the 


[Referencd book for information about writing these programs. 


Display Audit Journal Entries (DSPAUDJRNE) Command 

The Display Audit Journal Entries (DSPAUDJRNE) command allows you to 
generate security journal audit reports. The reports are based on the audit entry 
types and the user profile that are specified on the command. You can limit reports 
to specific time frames, and you can search detached journal receivers. You can 
direct these reports to the active display or an output queue. 


RESTRICTIONS: You must have *ALLOBJ and *AUDIT authorities to use this 
command. 


Refer to online help to see the parameter and value descriptions for this command. 


Default Public Authority for Newly Created Objects 


When objects are created in a library, the public authority for the object will, by 
default, be set by using the CRTAUT value of the library. 


By specifying: 

CRTLIB LIB(TESTLIB) CRTAUT(*USE) AUT(*LIBCRTAUT) 

The library TESTLIB is created. All objects created into library TESTLIB will, by 
default, have public authority of *USE. The public authority for library TESTLIB is 
determined by the CRTAUT value of library QSYS. 


By specifying: 
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CRTDTAARA DTAARA(TESTLIB/DTA1) TYPE(*CHAR) + 
AUT (*LIBCRTAUT) 


CRTDTAARA DTAARA(TESTLIB/DTA2) TYPE(*CHAR) + 
AUT (*EXCLUDE) 


Data area DTA1 is created into library TESTLIB. The public authority of DTA1 is 
*USE based on the CRTAUT value of library TESTLIB. 


Data area DTA2 is created into library TESTLIB. The public authority of DTA2 is 
*EXCLUDE. *EXCLUDE was specified on the AUT parameter of the Create Data 
Area (CRTDTAARA) command. 


An authorization list can also be used to secure an object when it is created into a 
library. 


By specifying: 
CRTAUTL AUTL(PAYROLL) 


CRTLIB LIB(PAYLIB) CRTAUT(PAYROLL) + 
AUT (*EXCLUDE) 


An authorization list called PAYROLL is created. Library PAYLIB is created with 
the public authority of “EXCLUDE. By default, an object created into library 
PAYLIB is secured by authorization list PAYROLL. 


By specifying: 
CRTPF FILE(PAYLIB/PAYFILE) + 
AUT (*LIBCRTAUT) 


CRTPF FILE(PAYLIB/PAYACC) + 
AUT (*CHANGE) 


File PAYFILE is created into library PAYLIB. File PAYFILE is secured by 
authorization list PAYROLL. The public authority of file PAYFILE is set to *AUTL 
as part of the Create Physical File (CRTPF) command. *AUTL indicates that the 
public authority for file PAYFILE is taken from the authorization list securing file 
PAYFILE, which is authorization list PAYROLL. 


File PAYACC is created into library PAYLIB. The public authority for file PAYACC 
is *CHANGE since it was specified on the AUT parameter of the CRTPF command. 


Note: The *LIBCRTAUT value of the AUT parameter that exists on most CRT 
commands indicates that the public authority for the object is set to the 
CRTIAUT value of the library that the object is being created into. 


The CRTAUT value on the library specifies the default authority for public use of 
the objects created into the library. These possible values are: 


*SYSVAL 
The public authority for the object being created is the value specified in 
system value QCRTAUT 


*ALL All public authorities 


*CHANGE 
Change authority 


*USE Use authority 
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*EXCLUDE 
Exclude authority 


authorization list name 
The authorization list secures the object 


Default Auditing Attribute for Newly Created Objects 


When objects are created in a library, the auditing attribute of the object will, by 
default, be set by using the CRTOBJAUD value of the library. 


By specifying: 
CRTLIB LIB(PAYROLL) AUT(*EXCLUDE) CRTAUT(*EXCLUDE) CRTOBJAUD(#*ALL) 


all objects created into the payroll library are audited for both read and change 
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Placing Objects in Libraries 


When you create an object, it is placed in a library. If you do not specify a library, 
the object is placed in the current library for the job (*“CURLIB) or, if there is no 
current library for the job, in QGPL. When a library is created, you can specify the 
public authority for objects created in the library by using the CRTAUT parameter 
on the Create Library (CRTLIB) command. All objects placed in that library will 
assume the specified public authority on the CRTAUT value of the library. To 
specify a library, you specify a qualified name; that is, a library name and an object 
name. For example, the following Create Physical File (CRTPF) command creates 
an order entry physical file ORDHDRP to be placed in DISTLIB. 


CRTPF FILE(DISTLIB/ORDHDRP) 


To place an object in a library, you must have read and add authorities for the 
library. 


More than one object of the same type cannot have the same name and be in the 
same library. For example, two files with the name ORDHDRP cannot both be in 
the library DISTLIB. If you try to place into a library an object of the same name 
and type as an object already in the library, the system rejects the request and 
sends you a message indicating the reason. 


Note: Use the QSYS library for system objects only. Do not restore other licensed 
programs to the QSYS library because changes are lost when installing a 
new release of OS/400. 


Deleting and Clearing Libraries 
When you delete a library with the Delete Library (DLTLIB) command, you delete 
the objects in the library as well as the library itself. When you clear a library with 
the Clear Library (CLRLIB) command, you delete objects in the library without 
deleting the library. To delete or clear a library, all you need to specify is the 
library name. For example: 
DLTLIB LIB(DISTLIB) 


or: 
CLRLIB LIB(DISTLIB) 
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To delete a library, you must have object existence authority for both the library 
and the objects within the library, and use authority for the library. If you try to 
delete a library but do not have object existence authority for all the objects in the 
library, the library and all objects for which you do not have authority are not 
deleted. All objects for which you have authority are deleted. If you try to delete a 
library but do not have object existence authority for the library, not only is the 
library not deleted, but none of the objects in the library are deleted. If you want 
to delete a specific object (for which you have object existence authority), you can 
use a delete command for that type of object, such as the Delete Program 
(DLTPGM) command. 


You cannot delete a library in an active job’s library list. You must wait until the 
end of the job before the deletion of the library is allowed. Because of this, you 
must delete the library before the next routing step begins. When you delete a 
library, you must be sure no one else needs the library or the objects within the 
library. 


If a library is part of the initial library list defined by the system values QSYSLIBL 

and QUSRLIBL, the following steps should be followed to delete the library: 

1. Use the Change System Value (CHGSYSVAL) command to remove the library 
from the system value it is contained in. (The changed system value does not 
affect the library list of any jobs running.) 

2. Use the Change Library List (CHGLIBL) command to change the job’s library 
list. 

The Change System Library List (CHGSYSLIBL), Add Library List Entry 
(ADDLIBLE), Edit Library List (EDTLIBL), and Remove Library List Entry 
(RMVLIBLE) commands are also used to change the library list. 


3. Use the DLTLIB command to delete the library and the objects in the library. 


Note: You cannot delete the library QSYS and should not delete any objects in it. 
You may cause the system to end because the system needs objects that are 
in QSYS to operate properly. You should not delete the library QGPL 
because it also contains some objects that are necessary for the system to be 
able to perform effectively. You should not use the library QRECOVERY 
because it is intended for system use only. The library QRECOVERY 
contains objects that the system needs to operate properly. 


For concerns about deleting objects other than libraries, see 


To clear a library, you must have object existence authority for the objects within 
the library and use authority for the library. If you try to clear a library but do not 
have object existence authority for all the objects in the library, the objects you do 
not have authority for are not deleted from the library. If an object is allocated to 
someone else, it is not deleted. 


Displaying Library Names and Contents 


You can use the Display Library (DSPLIB) or Work with Libraries (WRKLIB) 
command to display or print all the libraries you have authority to and find basic 
information on each object within the libraries. 


The object information includes: 
* The name and type of the object 
* The attributes of the object 
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* The size of the object 
* The description entered for the object when it was created 


On the DSPLIB command, you can also specify a specific library name or names, 

in which case you bypass the library selection display. In this list, the objects are 

grouped by library; within each library, they are grouped by object type; within 

each type, they are listed in alphanumeric order. The order of the libraries is one of 

the following: 

* If libraries are specified on the DSPLIB command, the libraries are displayed in 
the order they are specified in the display command. 

* If *LIBL or *USRLIBL is specified on the DSPLIB command, the order of the 
libraries matches the order of the libraries in the library list for the job. 

* If *ALL or *ALLUSR is specified on the DSPLIB command, the order of the 
libraries is in alphanumeric order. The user must have read authority for the 
library to be displayed. 


For example, the following DSPLIB command displays a list of the objects 
contained in DISTLIB: 


DSPLIB LIB(DISTLIB) OUTPUT(=) 


The asterisk (*) for the OUTPUT parameter means that the libraries are to be 
shown at the display station if in interactive processing and printed if in batch 
processing. To print a list when in interactive processing, specify *PRINT instead of 
taking the default *. 


See the CL section of the Programming category in the iSeries Information Center 
for more information and sample displays for the DSPLIB command. 


Displaying and Retrieving Library Descriptions 
You can use the Display Library Description (DSPLIBD) and Retrieve Library 


Description (RTVLIBD) commands to display and retrieve the description of 
libraries. 


The library description information includes: 

* Type of library (either PROD or TEST) 

* Auxiliary storage pool number of the library 

* Auxiliary storage pool device name of the library 
* Create authority of the library 

* Create object auditing of the library 

* Text description of the library 


OS/400 Globalization 


The OS/400 licensed program supports different national languages on the same 
system. This allows information in one national language to be presented to one 
user while information in a different national language is presented to another 
user. 


The language used for user-readable information (displays, messages, printed 
output, and online help information) is controlled by the library list for the job. By 
adding a national language library to the system portion of the library list, 
different national language versions of information can be presented. For the 
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primary language, a national language version is the running code and textual 
data for each licensed program entered. For the secondary language, it is the 
textual data for all licensed programs. 


The language information for the primary language of the system is stored in the 
same libraries as the programs for IBM licensed programs. For example, if the 
primary national language of the system is English, then libraries such as QSYS, 
QHLPSYS, and QSSP contain information in English. Libraries QSYS and 
QHLPSYS are on the system portion of the library list. Libraries for other licensed 
programs (such as ORPGLE for ILE RPG for OS/400*) are added to the library list 
by the system when they are needed. 


National language versions other than the system primary language are installed 
in secondary national language libraries. Each secondary language library contains 
a single national language version of the displays, messages, commands prompts, 
and help for all IBM licensed programs. The name of a secondary language library 
is in the form QSYSnnnn, where nnnn is a language feature code. For example, the 
feature code for French is 2928, so the secondary national language library name 
for French is OQSYS2928. 


If a user wants information presented in the primary national language of the 
system, no special action is required. To present information in a national language 
different from the primary national language of the system, the user must change 
the library list so that the desired national language library is positioned before all 
other libraries in the library list that contains national language information. You 
can use any of the following options to position the desired national language 
library first: 
* You can use the SYSLIBLE parameter on the CRTSBSD or CHGSBSD to present 
displays, messages, and so on for a specific language. For example: 


CRTSBSD SBSD(QSBSD 2928) POOLS((1 *NOTSG)) SYSLIBLE(QSYS2928) 


* You can use the LIB parameter on the CHGSYSLIBL command to specify the 
desired national language library at the top of the library list. For example: 


CHGSYSLIBL LIB(QSYS2928) 


* You can set up an initial program in the user profile to specify the desired 
national library at the top of the library list for an interactive job. This is a good 
option if the user does not want to run the CHGSYSLIBL command at every 
sign-on. The initial program uses the Change System Library List (CHGSYSLIBL) 
command to add the desired national language library to the top of the library 
list. 


Note: The authority shipped with the CHGSYSLIBL command does not allow 
all users to run the command. 


To enable a user to run the CHGSYSLIBL command without granting the user 
rights to the command, you can write a CL program containing the CHGSYSLIBL 
command. The program is owned by the security officer, and adopts the security 
officer’s authority when created. Any user with authority to run the program can 
use it to change the system part of the library list in the user’s job. The following is 
an example of a program to set the library list for a French user. 

PGM 


CHGSYSLIBL LIB(QSYS2928) /* Use French information «/ 
ENDPGM 
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Describing Objects 


Whenever you use a create command to create an object, you can describe the 
object in a 50-character field on the TEXT parameter of the create command. Some 
commands allow a default of *SRCMBRTXT which indicates the text for the object 
being created is to be taken from the text of the source member from which the 
object is being created. This is valid only for objects created from source in 
database source files. 


If the source input for the create command is a device or inline file, or if source is 
not used, the default value is blank. This text becomes part of the object 
description and can be displayed using the Display Object Description (DSPOBJD) 
or Display Library (DSPLIB) command. The text can be changed using the Change 
Object Description (CHGOBJD) command or many of the Change (CHGxxx) 
commands that are specific to each object type. 


Displaying Object Descriptions 


You can use the Display Object Description (DSPOBJD) or Work with Objects 
(WRKOBJ) command to display descriptions of objects. These descriptions are 
helpful for determining if objects exist on the system but are not being used. If you 
are using batch processing, the descriptions can be printed or written to a database 
file. If you are using interactive processing, the descriptions can be displayed, 
printed, or written to a database file. 


You can display basic, full, or service attributes for object descriptions. These object 
descriptions are found in the following table: 
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Table 2. Attributes Displayed for Object Descriptions 


Basic Attributes 


Object name 

Library name 

Library ASP device 
Object type 

Extended attribute 
Object size 

Text description (partial) 
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Full Attributes 


Object name 

Library name 

Library ASP device 
Object type 

Owner 

Primary Group 
Extended attribute 
User-defined attribute 
Text description 
Creation date and time 
User who created object 
System object created on 
Object domain 

Change date and time 


Whether or not usage data 
collected 


Last used date 

Days used count 

Days used count reset date 
Allow change by program 
Object auditing value 

Digitally signed 

Digitally signed system-trusted 
source 


Digitally signed multiple 
signatures 


Object size 

Offline size 

Freed status 
Compression status 
Object ASP number 
Object overflowed 
Object ASP device 
Journaling status 
Current or last journal 
Journal images 
Journal entries omitted 
Journal start date and time 


Save operation date and time 


Restore operation date and time 


Save command 


Device type 


Service Attributes (see 
Notes) 


Object name 
Library name 
Library ASP device 
Object type 


Source file and 
library 


Member name 
Extended attribute 


User-defined 
attribute 


Freed status 
Object size 
Creation date and 
time 

Date and time 


member in source 
file was last updated 


System level 
Compiler 

Object control level 
Changed by 
program 

Whether or not 
changed by user 
Licensed program 
PTF number 

APAR ID 


Text description of 
object or object 
status conditions 


Notes: 


1. The service information is used by programming support personnel to 
determine the level of the system on which an object was created and whether 
or not the object has been changed since it was shipped. Some of this 
information may be helpful to you because it indicates the source member used 
to create an object and the last date of change to that source from which the 
object was created. 

2. Library objects contain only the names of the objects included in the library. If 
DSPOBJD for object type *LIB is used, the object size information refers to the 
size of the library object only, not the total size of the objects included in the 
library. 

You can use either the Retrieve Library Description API (QLIRLIBD) or the 
command DSPLIB OUTPUT(*PRINT) to find the total size of the library. 


Using the DSPOBJD or WRKOBJ command, you can list the objects in a library for 
which you are authorized by: 

* Name 

* Generic name 

* Type 

* Name or generic name within object type 


The objects are listed by library; within a library, they are listed by type. Within 
object type, the objects are listed in alphanumeric order. 


You may want to use the DSPOBJD command in a batch job if you want to display 
many objects with the *FULL or *SERVICE option. The output can go to a spooled 
printer file and be printed instead of being shown at the display station, or the 
output can go to a database file. If you direct the output to a database file, all the 
attributes of the object are written to the file. Use the Display File Field Description 
(DSPFFD) command for file QADSPOBJ, in library QSYS, to view the record 
format for this file. 


The following command displays the descriptions of the order entry files (that is, 
the files in DISTLIB) whose names begin with ORD. ORD* is the generic name. 
DSPOBJD  OBJ(DISTLIB/ORD*) OBJTYPE(*FILE) + 

DETAIL(*BASIC) OUTPUT(+) 


The resulting basic display is: 
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Display Object Description - Basic 
Library 1 of 1 
Library . ... .. : DISTLIB Library ASP device . : *SYSBAS 


Type options, press Enter. 
5=Display full attributes 8=Display service attributes 


Opt Object Type Attribute Size Text 
_  ORDDTLP *FILE PF 8192 Order detail 
ORDHDRP *FILE PF 8192 Order header 


Bottom 
F3=Exit F12=Cancel Fl7=Top F18=Bottom 


: 


If you specify *FULL instead of *BASIC or if you enter a 5 in front of ORDDTLP 
on the basic display, the resulting full display is: 


Display Object Description - Full 
Library 1 of 1 

ObJeGtiecs 4 fort nels ORDDTLP Attribute: 3 <2 2.2 PE 

Eibrary 4 0. 2 DISTLIB Owner 332% 2 « = 2  (QSECOFR 
Library ASP device . : *SYSBAS Primary group . . . : *NONE 
UY POs se) Resesaveu esse eae cs *FILE 
User-defined information: 

AGCRIDULG ce. exc nse ci eras eeree tae 

TOXC ee eiesn eon ken ours) sake mono comers 
Creation information: 

Creation date and time. ..... : 06/08/89 10:17:03 

Created by user «. <3 6% 6 s a = 3% ‘QSECOFR 

System created on ....... =. 2: SYSTEMOL 

OBGECt domains vex sntatee ces te nee eaeee ce *SYSTEM 
Change/Usage information: 

Change date/time. ........ : 05/11/90 10:03:02 

Usage data collected ........:  #4YES 

Last used date... 2 ss.» =. 2 05/11/90 

Days:usedi count: 2:02) 2% ncaca ce  -20 

Resetadate:, @ sfc. ee cane ct? 03/10/90 

Allow change by program .....: ~~ YES 
Auditing information: 

Object auditing value ......:  *NONE 

Digitally Signed 23 33% 243% % INO 
Press Enter to continue. 

Weare F12=Cancel (C) COPYRIGHT IBM CORP. 1980, 1993. 
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a a 
Display Object Description - Full 
Library 1 of 1 

Object. 5 <= ss « 3 ORDDTLP AGEMIDUEE, “cae ens xn PF 

[EVID NAY ies ese ot nero as DISTLIB OWNER fae ee QSECOFR 
NY PCwen ce aepceten eM tom es *FILE 
Storage information: 

Si1Z Coa careseray teeter cars ak acnrs ice ee W can tnyen ES 8192 

ORRTAINEUSTZEs Se Re wie Ge eee es a 0 

CCU Mercicu onset aicrse carrier cues eons NO 

Compressediicac. sce c0 ee Mier on ter von oes NO 

Obyect! ASP number ‘i757 So tes ae ase i 

Object overflowed ........: NO 

ObyectsASP device: 2 2. ane *SYSBAS 

Object overflowed .......: NO 
Journaling information: 
Currently journaled . «... 5% 4 NO 

Save/Restore information: 

Save. date/time... @ a 64 80 a 

Restore date/time ........: 

SavenCommandiz. ts. s:eeacsecen suey cee ted Geo 

Devices ty per reap sien os cas fon eas cog petes 

Bottom 
Press Enter to continue. 
F3=Exit F12=Cancel 
C) COPYRIGHT IBM CORP. 1980, 1993. 
L i J 


Retrieving Object Descriptions 


You can use the Retrieve Object Description (RTVOBJD) command to return the 
descriptions of a specific object to a CL procedure. Variables are used to return the 
descriptions. You can use these descriptions to help you detect unused objects on 
the system. 


The command can return the following descriptions as variables for an object: 


The name of the library that contains the object 

Any extended attribute of an object (such as program or file type) 
User-defined attribute 

Text description of the object 

Name of the object owner’s user profile 

Name of the primary group for the object 

Object ASP number 

Library ASP number 

Object ASP device 

Library ASP device 

Indication of whether or not the object overflowed the ASP in which it resides 
Date and time the object was created 

Date and time the object was last changed 

Date and time the object was last saved 


Date and time the object was last saved during a SAVACT (*LIB, *SYSDEN, or 
*YES) save operation 


Date and time the object was last restored 
Name of the object creator’s user profile 
System the object was created on 
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* Object domain 

* Digitally signed system-trusted source 

* Digitally signed multiple signatures 

* Whether or not usage data was collected 

* Date the object was last used 

* Count (number) of days the object was used 

* Date the use count was last reset 

* Storage status of the object data 

* Compression status of the object 

* Size of the object in bytes 

* Size of the object in bytes of storage at the time of the last save 

* Command used to save the object 

* Tape sequence number generated when the object was saved on tape 

* Tape or diskette volumes used for saving the object 

* Type of the device the object was last saved to 

* Name of the save file if the object was saved to a save file 

* Name of the library that contains the save file if the object was saved to a save 
file 

* File label used when the object was saved 

* Name of the source file that was used to create the object 

* Name of the library that contains the source file that was used to create the 
object 

* Name of the member in the source file 

* Date and time the member in the source file was last updated 

* Level of the operating system when the object was created 

* Licensed program identifier, release level, and modification level of the compiler 

* Object control level for the created object 


* Information about whether or not the object can be changed by the Change 
Object Description (QLICOBJDD) API 


* Indication of whether or not the object has been modified with the Change 
Object Description (QLICOBJD) API 


* Information about whether or not the program was changed by the user 


* Name, release level, and modification level of the licensed program if the 
retrieved object is part of a licensed program 


* Program Temporary Fix (PTF) number that resulted in the creation of the 
retrieved object 


* Authorized Program Analysis Report (APAR) identification 
* Type of auditing for the object 

* Whether or not the object is digitally signed 

* Current journal status for the object 

* Current or last journal 

* Journal image information 

¢ Journal entries to be omitted information 


* The date and time that journaling was last started 
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RTVOBJD Example 


In the following CL procedure, a RTVOBJD command retrieves the description of a 
specific object. Assume an object called MOBJ exists in the current library (MYLIB). 


DCL 
DCL 
DCL 
DCL 
DCL 


&LIB TYPE(*CHAR) LEN(10) 
&CRTDATE TYPE(*CHAR) LEN(13) 
&USEDATE TYPE(*CHAR) LEN(13) 
&USECNT TYPE(*DEC) LEN(5 0) 
&RESET  TYPE(*CHAR) LEN(13) 


RTVOBJD  OBJ(MYLIB/MOBJ) OBJTYPE(*FILE) RTNLIB(&LIB) 


CRTDATE(&CRTDATE) USEDATE(&USEDATE) 
USECOUNT (&USECNT) RESETDATE (&RESET) 


The following information is returned to the program: 


* The current library name (MYLIB) is placed into the CL variable name &LIB. 

* The creation date of MOBJ is placed into the CL variable called &CRIDATE. 

* The date that MOBJ was last used is placed into the CL variable called 
&USEDATE. 


* The number of days that MOBJ has been used is placed into the CL variable 
called &USECNT. The start date of this count is the value placed into the CL 
variable called &RESET. 


Creation Information for Objects 


The following information is provided in the object description and is set when the 
object is created. It is useful for object management and maintenance. 


* Creator of the object 


The creator of the object is the user profile that is performing the create 
operation. This is true even if the user profile has a group profile and the 
group profile owns the object. 


The creator of the object does not change when the ownership changes. 


The creator is the creator of the object on the media when an object is 
restored. 


The creator of the object is the user running the command when an object is 
duplicated using the Create Duplicate Object (CRTDUPOBJ) command. 


The creator is *1BM for IBM-supplied objects. 


The creator of the object is blank for user objects that already existed on the 
system before Version 1, Release 3.0. 


* System on which the object was created 


When an object is restored, the system created on is the system the object on 
the media was created on. 


For IBM-supplied objects, the system created on is 00000000. 


For objects that already existed on the system before Version 1, Release 3.0, 
the system that is created is blank. 


Detecting Unused Objects on the System 


Information provided in the object description can help you detect and manage 
unused objects on the system. 
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To detect an unused object, look at both the last-used date and the last-changed 
date. Change commands do not update the last-used date unless the commands 
cause the object to be deleted and created again, or the change operation causes 
the object to be read as a part of the change. 


* Date and time of last change 


— When an object is created or changed, the system time stamps the object, 

indicating the date and time the change occurred. 
* Date of last use 

— The date of last use is only updated once per day (the first time an object is 
used in a day). The system date is used. 

— An unsuccessful attempt to use an object does not update the last used date. 
For example, if a user tries to use an object for which the user is not 
authorized, the date of last use does not change. 

— The date of last use is blank for new objects. 

— When an object that already exists on the system is restored, the date of last 
use comes from the object on the system. If it does not already exist when 
restored, the date is blank. 


— Objects that are deleted and re-created during the restore operation lose the 
date of last use. 

— The last used date for a database file is not updated when the number of 
members in the file is zero. For example, if you use the CRTDUPOBJ to copy 
objects and there are no members in the database file, the last used date is not 
updated. 

— The last used date for a database file is the last used date of the file member 
with the most current last used date. 

— For logical files, the last used date is the last time a logical member (or 
cursor) was used. 


— For physical files, the last used date is the last time the data in the data space 
was used through a physical or logical access. 


[able 3] contains additional information about operations that cause the last-used 
date to be updated for various object types. 


Table 3. Updating Usage Information 


Type of Object Commands and Operations 


All object types Create Duplicate Object (CRTDUPOBJ) command and 
other commands, such as the Copy Library (CPYLIB) 
command, that use CRTDUPOBJ to copy objects. 


Grant Object Authority (GRTOBJAUT) command (for 
referenced objects) 


Binding directory When bound with another module or binding directory 
to create a bound program (CRTPGM command) or 
bound service program (CRTSRVPGM command). 
When updated on the Update Program UPDPGM 
command or Update Service Program (UPDSRVPGM 


command). 

Change Request Description Change Command Change Request Activity 
(CHGCMDCRQA) 

Chart format Display Chart (DSPCHT) command 

C locale description Retrieve C Locale Description Source (RTVCLDSRC) 


command or when referred to in a C program 
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Table 3. Updating Usage Information (continued) 


Type of Object 


Commands and Operations 


Class 


When used to start a job 


Command 


When run 
When compiled in a CL program 


When prompted during entry of source entry utility 
(SEU) source 


When calling the system in check mode 
Note: Prompting from the command line and then 
pressing F3 is not counted as a use of a command. 


Communications side information 


(CSI) 


When the CPI-Communications Initialize Conversation 
(CMINIT) call is used to initialize values for various 
conversation characteristics from the side information 
object. 


Connection list 


When the connection list goes beyond status of vary on 
pending 


Cross system product map 


When referred to in a CSP application 


Cross system product table 


When referred to in a CSP application 


Controller description 


When the controller goes beyond status of vary on 
pending 


Device description 


When the device goes beyond status of vary on 
pending 


Data area 


Data queue 


Retrieve Data Area (RTVDTAARA) command 


Display Data Area (DSPDTAARA) command 


Usage information for the following APIs is updated 
only once per job (the first time one of the APIs is 
initiated). 


Send Data Queue (QSNDDTAQ) API 
Receive Data Queue (QRCVDTAQ) API 
Retrieve Data Queue (QMHOQRDOQD) API 


Read Data Queue (QMHRDQM) API 


File (database file only unless 
specified otherwise) 


When closed (other files, such as device and save files, 
also updated when closed) 


When cleared 
When initialized 
When reorganized 


Commands: 
¢ Apply Journaled Changes (APYJRNCHG) command 


* Remove Journaled Changes (RMVJRNCHG) 
command 


Font resource 


Form definition 


When referred to during a print operation 


When referred to during a print operation 
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Table 3. Updating Usage Information (continued) 


Type of Object 


Commands and Operations 


Graphics symbol set 


When referred to by a GDDM* or PGR graphics 
application program 


When loaded internally or using GSLSS 


Job description 


When used to establish a job 


Job schedule 


When the system submits a job for a job schedule entry 


Job queue 


Line description 


When an entry is placed on or removed from the 
queue 


When the line goes beyond status of vary on pending 


Locale 


Retrieve locale API OLGRTVLC 


When a job starts if the user profile LOCALE value 
contains a path name to a valid *LOCALE object. 


Management collection 


Only updated by commands and operations that affect 
all object types. 


Media definition 


The SAVLIB, SAVOBJ, RSTLIB, RSTOBJ, SAVCHGOBJ 
commands; as well as, the BRMS and QSRSAVO API. 


Menu 


When a menu is displayed using the GO command 


Message files 


When a message is retrieved from a message file other 
than QCPFMSG, ##MSG1, ##MSG2, or QSSPMSG (such 
as when a job log is built, a message queue is 
displayed, help is requested on a message in the QHST 
log, or a program receives a message other than a mark 
message) 


Merge Message File (MRGMSGF) command except 
when the message file is QCPFMSG, ##MSG1, ##MSG2, 
or QSSPMSG 


Message queue 


When a message is sent to, received from, or listed 
message queue other than QSYSOPR and QHST 


Module 


When bound with another module or binding directory 
to create a bound program (CRTPGM command) or 
bound service program (CRTSRVPGM command). 
When updated on the Update Program UPDPGM 
command or Update Service Program (UPDSRVPGM 
command). 


Network interface description 


When the network interface description goes beyond 
status of vary on pending 


Node List 


Only updated by commands and operations that affect 
all object types 


Output queue 


When an entry is placed on or removed from the 
queue 


Overlay 


When referred to during a print operation 


Page definition 


When referred to during a print operation 


Page segment 


When referred to during a print operation 
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Table 3. Updating Usage Information (continued) 


Type of Object 


Commands and Operations 


Panel group 


When the Help key is used to request help information 
for a specific prompt or panel, the date of usage is 
updated 


When a panel is displayed or printed from a panel 
group 


Print descriptor group 


When referred to during a print operation 


Product Availability 


Only updated by commands and operations that affect 
all object types 


Product Load 


Only updated by commands and operations that affect 
all object types 


Program 


Retrieve CL Source (RTVCLSRC) command 


When run and not a system program 


PSF Configuration 


When referred to during a print operation 


Query definition 


When used to generate a report 


When extracted or exported 


Query manager form 


When used to generate a report 


When extracted or exported 


Query manager query 


When used to generate a report 


When extracted or exported 


Search index 


When the F11 key is used through the online help 
information 


When the Start Search Index (STRSCHIDX) command 
is used 


Server storage 


Vary Configuration (VRYCFG) is run against a network 
server description object 


Service program 


When a bound service program is activated 


SQL Package 


Only updated by commands and operations that affect 
all object types 


Subsystem description 


When subsystem is started 


Spelling aid dictionary 


When used to create another dictionary 
When retrieved 


When a word is found in the dictionary during a spell 
check and the dictionary is not an IBM-supplied 
spelling aid dictionary 


Table 


When used by a program for translation 


User profile 


When a job is initiated for the profile 


When the profile is a group profile and a job is started 
using a member of the group 


Grant User Authority (GRTUSRAUT) command (for 
referenced profile) 


Workstation User Customization 


Only updated by commands and operations that affect 
all object types 
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Table 3. Updating Usage Information (continued) 


Type of Object Commands and Operations 


When the user takes ‘Option 10 = submit immediately’ 
from the WRKJOBSCDE panel 


The following is additional object usage information provided in the object 
description: 


* Counter of number of days used 
— The count is increased when the date of last use is updated. 


— When an object that already exists on the system is restored, the number of 
days used comes from the object on the system. If it does not already exist 
when restored, the count is zero. 


— Objects that are deleted and re-created during the restore operation lose the 
days used count. 


— The days used count is zero for new objects. 


Note: The iSeries server cannot determine the difference between old and new 
device files. If you restore a device file on to the system and a device 
file of that same name already exists, delete the existing file if you 
want the days used count to be reset to zero. If the file is not deleted, 
the system will interpret this as a restore operation of an old object and 
retain the days used count. 

— The days used count for a database file is the sum of the days used counts for 
all file members. If there is an overflow on the sum, the maximum value (of 
the days used counts field) is shown. 

* Date days used count was reset 

— When the days used count is reset using the Change Object Description 
(CHGOBJD) command or the Change Object Description (QLICOBJD) API, 
the date is recorded. The user then knows how long the days used count has 
been active. 

— If the days used count is reset for a file, all of the members have their days 
used count reset. 


Common situations that can delete the days used count and the last used date are 
as follows: 


* Restoring damaged objects on the system. 
* Restoring programs when the system is not in a restricted state. 


The Display Object Description (DSPOBJD) command can be used to display a full 
description of an object. You can use the same command to write the description to 
an output file. To retrieve the descriptions, use the Retrieve Object Description 
(RTVOBJD) command. 


Note: The application programming interface (API), QUSROBJD, provides the 
same information as the Retrieve Object Description command. For more 
information, see the APIs section of the Programming category for the 
iSeries Information Center. 


The Retrieve Member Description (RTVMBRD) command and Display File 
Description (DSPFD) command provide similar information for members in a file. 


Object usage information is not updated for the following object types: 
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Alert table *ALRTBL) 

¢ Authorization list *AUTL) 

* Configuration list (*CFGL) 

* Class-of-service description (*COSD) 

* Data Dictionary (*DTADCT) 

* Document (*DOC) 

* Double-byte character set dictionary (*IGCDCT) 
* Double-byte character set sort (*IGCSRT) 
* Double-byte character set table (*IGCTBL) 
* Edit description (*EDTD) 

* Exit Registration (*EXITRG) 

° Filter *FTR) 

* Forms control table (*FCT) 

* Folder (*FLR) 

* Internet Packet Exchange Description (*IPXD) 
* Journal (*JRN) 

* Journal receiver (*JRNRCV) 

* Library (*LIB) 

* Mode description (*MODD) 

* Network Server Description (*NWSD) 

* NetBIOS Description (*NTBD) 

* Product definition (*PRDDFN) 

* Reference code translation table (*RCT) 

* Session description (*SSND) 

* S/36 machine description (*S36) 

* User-defined SQL type (GSQLUDT) 

* User queue (*USRQ) 


Moving Objects from One Library to Another 


You can use the Move Object (MOVOBJ) command to move objects between 
libraries. Moving objects from one library to another is useful in that you make an 
object temporarily unavailable and it lets you replace an out-of-date version of an 
object with a new version. For example, a new primary file can be created to be 
temporarily placed in a library other than the one containing the old primary file. 
Because the data in the old primary file is normally copied to the new primary file, 
the old primary file cannot be deleted until the new primary file has been created. 
Then, the old primary file can be deleted and the new primary file can be moved 
to the library that contained the old primary file. 


You can only move an object if you have object management authority for the 
object, delete and execute authority for the library the object is being moved from, 
and add and read authority to the library the object is being moved to. 


You can move an object out of the temporary library, QTEMP, but you cannot 
move an object into QTEMP. Also, you cannot move an output queue unless it is 


empty. 
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Moving journals and journal receivers is limited to moving these object types back 
into the library in which they were originally created. If the journal objects have 
been placed into QRCL by a Reclaim Storage (RCLSTG) command, they must be 
moved back into their original library to be made operational. 


The following is a list of objects that cannot be moved: 
¢ Authorization lists (*AUTL) 

* Class-of-service descriptions (*COSD) 

* Cluster resource group (*CRG) 

* Configuration lists (*CFGL) 

* Connection lists (*CNNL) 

* Controller descriptions (*CTLD) 

* Data dictionaries (*DTADCT) 

* Device descriptions (*DEVD) 

* Display station message queues (*MSGQ) 

* Documents (*DOC) 

* Edit descriptions (*EDTD) 

* Exit registration (*EXITRG) 

* Folders (*FLR) 

* Double-Byte Character Set (DBCS) font tables (*IGCTBL) 
* Image catalog (*IMGCLG) 

* Internet Packet Exchange Description (*IPXD) 

* Job schedules (*JOBSCD) 

¢ Libraries (*LIB) 

* Line descriptions (*LIND) 

* Mode descriptions (*~MODD) 

* NetBIOS description (*NTBD) 

* Network interface descriptions (*NWID) 

* Structured Query Language (SQL) packages (*SQLPKG) 
* System/36'" machine descriptions (*S36) 

* The system history log (QHST) 

* The system operator message queue (QSYSOPR) 

* User-defined SQL type (*SQLUDT) 

* User profiles (*USRPRF) 


In the following example, a file from QGPL (where it was placed when it was 
created) is moved to the order entry library DISTLIB so that it is grouped with 
other order entry files. 


QGPL (before) DISTLIB QGPL (after) 
a MOVOBJ ee (ORDFILL 
ORDFILL =} —| ss | is gone) 
eee eee ——» ORDFILL ae ae 

RBAFN528-0 


To move the object, you must specify the to-library (TOLIB) as well as the object 
type (OBJTYPE): 
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MOVOBJ OBJ(QGPL/ORDFILL) OBJTYPE(*FILE) TOLIB(DISTLIB) 


When you move objects, you should be careful not to move objects that other 
objects depend on. For example, CL procedures may depend on the command 
definitions of the commands used in the procedure to be in the same library at run 
time as they were at module creation time. At compile time and at run time, the 
command definitions are found either in the specified library or in a library in the 
library list if *LIBL is specified. If a library name is specified, the command 
definitions must be in the same library at run time as they were at compile time. If 
*LIBL is specified, the command definitions can be moved between compile time 
and program run time as long as they are moved to a library in the library list. 
Similarly, any application program you write can depend on certain objects being 
in specific libraries. 


An object referring to another object may be dependent on the location of that 
object (even though *LIBL can be specified for the location of the object). Therefore, 
if you move an object, you should change any references to it in other objects. The 
following lists examples of objects that refer to other objects: 


* Subsystem descriptions refer to job queues, classes, message queues, and 
programs. 


* Command definitions refer to programs, message files, help panel groups, and 
source files that are containing REXX procedures. 


* Device files refer to output queues. 

* Device descriptions refer to translation tables. 

* Job descriptions refer to job queues and output queues. 
* Database files refer to other database files. 

* Logical files refer to physical files or format selections. 


* User profiles refer to programs, menus, job descriptions, message queues, and 
output queues. 


* CL programs refer to display files, data areas, and other programs. 
* Display files refer to database files. 
* Printer files refer to output queues. 


Note: You should be careful when moving objects from the system library QSYS. 
These objects are necessary for the system to perform effectively and the 
system must be able to find the objects. This is also true for some of the 
objects in the general-purpose library QGPL, particularly for job and output 
queues. 


The MOVOBJ command moves only one object at a time. 


Creating Duplicate Objects 


You can use the Create Duplicate Object (CRTDUPOBJ) command to create a copy 
of an existing object. The duplicate object has the same object type and 
authorization as the original object and is created into the same auxiliary storage 
pool (ASP) as the original object. The user who issues the command owns the 
duplicate object. 


Notes: 


1. If you create a duplicate object of a journaled file, the duplicate object (file) will 
not have journaling active. However, you can select this object for journaling 
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later. If you create a duplicate object and the object (file) has no members, the 
last used date field is blank and the count for number of days used is zero. 


You can duplicate an object if you have object management and use authority for 
the object, use and add authority for the library in which the duplicate object is to 
be placed, use authority for the library in which the original object exists, and add 
authority for the process user profile. 


To duplicate an authorization list, you must have authorization list management 
authority for the object and both add and object operational authority for library 
OSYS. 


Only the definitions of job queues, message queues, output queues and data 
queues are duplicated. Job queues and output queues cannot be duplicated into 
the temporary library (QTEMP). For a physical file or a save file, you can specify 
whether the data in the file is also to be duplicated. 


The following objects cannot be duplicated: 
* Class-of-service descriptions (*COSD) 

* Cluster resource group (*CRG) 

* Configuration lists (*CFGL) 

* Connection lists (*CNNL) 

* Controller descriptions (*CTLD) 

* Data dictionaries (*DTADCT) 

* Device descriptions (*DEVD) 

* Data queues (*DTAQ) 

* Documents (*DOC) 

* Edit descriptions (*EDTD) 

* Exit registration (*EXITRG) 

* Folders (*FLR) 

* DBCS font tables (*IGCTBL) 

* Image catalog (*IMGCLG) 

* Internet Packet Exchange Description (*IPXD) 
* Job schedules (*JOBSCD) 

¢ Journals (*JRN) 

¢ Journal receivers (*JRNRCV) 

* Libraries (*LIB) 

* Line descriptions (*LIND) 

* Mode descriptions (*MODD) 

* Network interface descriptions (*NWID) 
* Network server descriptions (*NWSD) 

* Reference code translation tables (*RCT) 
* Server storage (*SVTSTG) 

* Spelling aid dictionaries (*“SPADCT) 

* SOL packages (*SOQLPKG) 

* System/36 machine descriptions (*S36) 

* System operator message queue (QSYSOPR) 
* System history log (QHST) 
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* User-defined SQL type (*‘SQLUDT) 
* User profiles (*USRPRF) 
* User queues. (*USRQ) 


In some cases, you may want to duplicate only some of the data in a file by 
following the CRTDUPOBJ command with a CPYF command that specifies the 
selection values. 


The following command creates a duplicate copy of the order header physical file, 
and duplicates the data in the file: 


CRTDUPOBJ OBJ(ORDHDRP) FROMLIB(DSTPRODLIB) OBJTYPE(*FILE) + 
TOLIB(DISTLIB2) NEWOBJ(*SAME) DATA(*YES) 


When you create a duplicate object, you should consider the consequences of 
creating a duplicate of an object that refers to another object. Many objects refer to 
other objects by name, and many of these references are qualified by a specific 
library name. Therefore, the duplicate object could contain a reference to an object 
that exists in a library different from the one in which the duplicate object resides. 
For all object types other than files, references to other objects are duplicated in the 
duplicate object. For files, the duplicate objects share the formats of the original 
file. 


Any physical files which exist in the from-library, and on which a logical file is 
based, must also exist in the to-library. The record format name and record level ID 
of the physical files in the to- and from-libraries are compared; if the physical files 
do not match, the logical file is not duplicated. 


If a logical file uses a format selection that exists in the from-library, it is assumed 
that the format selection also exists in the to-library. 


Renaming Objects 


You can use the Rename Object (RNMOBJ) command to rename objects. However, 
you can rename an object only if you have object management authority for the 
object and update and execute authority for the library containing the object. 


To rename an authorization list, you must have authorization list management 
authority, and both update and read authority for library QSYS. 


The following objects cannot be renamed: 
* Class-of-service descriptions (*COSD) 
* Cluster resource group (*CRG) 

¢ Data dictionaries (*‘DTADCT) 

* DBCS font tables *IGCTBL) 

* Display station message queues (*MSGQ) 
* Documents (*DOC) 

* Exit Registration (*EXITRG) 

Folders (*FLR) 

Job schedules (*JOBSCD) 

Journals (*JRN) 

* Journal receivers (*JRNRCV) 

* Mode descriptions (*~MODD) 
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* Network Server Description (*“NWSD) 

* SOL packages (*SQLPKG) 

* System/36 machine descriptions (*S36) 

* The system history log (QHST) 

* The system library, QSYS, and the temporary library, QTEMP 
* The system operator message queue (QSYSOPR) 

* User-defined SQL type (*SQLUDT) 

* User profiles (*USRPRF) 


Also, you cannot rename an output queue unless it is empty. You should not 
rename IBM-supplied commands because the licensed programs also use 
IBM-supplied commands. 


To rename an object, you must specify the current name of the object, the name to 
which the object is to be renamed, and the object type. 


The following RNMOBJ command renames the object ORDERL to ORDFILL: 
RNMOBJ OBJ(QGPL/ORDERL) OBJTYPE(*FILE) | NEWOBJ(ORDFILL) 


You cannot specify a qualified name for the new object name because the object 
remains in the same library. If the object you want to rename is in use when you 
issue the RNMOBJ command, the command runs, but does not rename the object. 
As a result, the system sends you a message. 


When you rename objects, you should be careful not to rename objects that other 
objects depend on. For example, CL programs depend on the command definitions 
of the commands used in the program to be named the same at run time as they 
were at compile time. Therefore, if the command definition is renamed in between 
these two times, the program cannot be run because the commands will not be 
found. Similarly, any application program you write depends on certain objects 
being named the same at both times. 


You cannot rename a library that contains a journal, journal receiver, data 
dictionary, cluster resource group, or SQL package. 


An object referring to another object may be dependent on the object and library 
names (even though *LIBL can be specified for the library name). Therefore, if you 
rename an object, ou should change an zeterences to it in other objects. See 


that refer to other objects. 


If you rename a physical or logical file, the members in the file are not renamed. 
However, you can use the Rename Member (RNMM) command to rename a 
physical or logical file member. 


Note: You should be careful when renaming objects in the system library QSYS. 
These objects are necessary for the system to perform effectively and the 
system must be able to find the objects. This is also true for some of the 
objects in the general-purpose library QGPL. 
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Compressing or Decompressing Objects 


You can use the Compress Object (CPROBJ) command to compress selected objects 
in order to save disk space on the system or you can use the Decompress Object 
(DCPOBJ) command to decompress objects that have been compressed. The object 
types that are supported for compression and decompression are *PGM, *SRVPGM, 
*MODULE, *PNLGRP, *MENU (only UIM menus), and *FILE (only display files or 
print files). Database files are not allowed to be compressed. Customer objects, as 
well as OS/400-supplied objects, may be compressed or decompressed. To see or 
retrieve the compression status of an object, use the Display Object Description 
(DSPOBJD) command (*FULL display), or the Retrieve Object Description 
(RTVOBJD) command. 


Compression of Objects 


Object types, *PGM, *SRVPGM, *MODULE, *PNLGRP, *MENU, and *FILE (display 
and print files only) can be compressed or decompressed using the CPROBJ or 
DCPOBJ commands. Objects can be compressed only when both of the following 
are true: 


* If the system can obtain an exclusive lock on the object. 
* When the compressed size saves disk space. 


The following restrictions apply to the compression of objects: 

* Programs created before Version 1 Release 3 of the operating system cannot be 
compressed. 

* Programs, service programs, or modules created before Version 3 Release 6 of 
the operating system that have not been translated again cannot be compressed. 

* Programs in IBM-supplied libraries QSYS and QSSP cannot be compressed 
unless the paging pool value of the program is *BASE. Use the Display Program 
(DSPPGM) command to see the paging pool value of a program. Programs in 
libraries other than QSYS and QSSP can be compressed regardless of their 
paging pool value. 

* Only menus with the attribute UIM can be compressed. 

* Only files with attributes DSPF and PRTF can be compressed. 


* The system must be in restricted state (all subsystems ended) in order to 
compress program objects in system libraries. 


* The program must not be running in the system when it is compressed, or the 
program will end abnormally. 


Compression runs much faster if you use multiple jobs in nonrestricted state as 
shown in the following table: 


Table 4. Compressing Objects using Multiple Jobs 


Object Type IBM-supplied User-supplied 
*FILE Job 3: QSYS Job 7: USRLIB1 
*MENU Job 2: QSYS Job 8: USRLIB1 
*MODULE Not applicable Job 10: USRLIB1 
*PGM Restricted State Only Job 5: USRLIB1 
*PNLGRP Job 1: QSYS Job 4: QHLPSYS Job 6: USRLIB1 
*SRVPGM Job 11: QSYS Job 9: USRLIB1 
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Temporarily Decompressed Objects 


Compressed objects are temporarily decompressed automatically by the system 
when used. A temporarily decompressed object will remain temporarily 
decompressed until: 

* An IPL of the system. This causes the temporarily decompressed object to be 
deleted (the compressed object remains). 

* A Reclaim Temporary Storage (RCLTMPSTG) command is used to reclaim 
temporarily decompressed objects. This causes temporarily decompressed objects 
to be deleted (the compressed objects remain) if the objects have not been used 
for a specified number of days. 

* The temporarily decompressed object is used more than 2 days or more than 5 
times on the same IPL, in which case it is permanently decompressed. 

* A DCPOBJ command is used to decompress the object, in which case it is 
permanently decompressed. 


* The system has an exclusive lock on the object. 


Notes: 


1. Objects of the type *PGM, *SRVPGM, or *MODULE cannot be temporarily 
decompressed. If you call a compressed program or debug the program, it is 
automatically permanently decompressed. 

2. Compressed file objects, when opened, are automatically decompressed. 

3. If the description of a compressed file is retrieved, the file is temporarily 
decompressed. Two examples of retrieving a file are: 

* Using the Display File Field Description (DSPFFD) command to display field 
level information of a file. 
* Using the Declare File (DCLF) command to declare a file. 


Automatic Decompression of Objects 


Compressed objects shipped in the OS/400 or other IBM licensed programs are 
decompressed by the system after the licensed programs are installed. The 
decompression occurs only when sufficient storage is available on the system. 


System jobs called QDCPOBJx are automatically started by the system to 
decompress objects. 


The number of QDCPOB]J jobs is based on number of processors + 1. The jobs are 
system jobs running at priority 60 which can’t be changed, ended or held by the 
user. A QDCPOBJx job may be in one of the following statuses, which are from the 
Work Active Job (WRKACTJOB) command: 


* RUN (running): The job is actively decompressing objects. 

* EVTW (event wait): The job is not actively decompressing objects. The job is 
active in case more objects need to decompressed (i.e. additional licensed 
programs are installed). 

* DLYW (delay wait): The job is temporarily halted. The following situations could 
cause the QDCPOBJx jobs to halt: 

— The system is running in restricted state (i.e. ENDSYS or ENDSBS *ALL was 
executed) 

- Alicensed program was just installed from the "Work with Licensed 
Programs” display. The job is in a delay wait state for a maximum of 15 
minutes prior to starting to decompress objects. 
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* LCKW (lock wait): The job is waiting for an internal lock. Typically, this occurs 
when one QDCPOBJ job is in DLYW state. 


The following storage requirements apply if the operating system was installed 
over an existing operating system: 


* The system must have greater than 250 megabytes of unused storage for the 
QDCPOB)Jx jobs to start. 


* Ona system with available storage of greater than 750MB, the jobs are 
submitted to decompress all system objects just installed. 


* Ona system with available storage of less than 250MB, jobs are not submitted, 
and the objects are decompressed as they are used. 


* Ona system with available storage between 250MB and 750MB, only 
frequently-used objects are automatically decompressed. 


Frequently-used objects are objects that have been used at least five times and the 
last use was within the last 14 days. The remaining low-use objects remain 
compressed. 


The system must have greater than 1000MB of unused storage if the operating 
system is installed on a system that has been initialized using options 2, Install 
Licensed Internal Code and Initialize the system, from the Install Licensed Internal 
Code (LIC) display. 


If QDCPOBJx jobs are active at the last system termination, the jobs are started 
again at the time of the next IPL. 


Deleting Objects 


To delete an object, you can use a delete (DLTxxx) command for that type of object 
or you can use the delete option on the Work with Objects display (shown from 
the Work with Libraries (WRKLIB) display). To delete an object, you must have 
object existence authority to the object and execute authority to the library. Only 
the owner of an authorization list, or a user with *ALLOBJ special authority, can 
delete the authorization list. 


When you delete an object, you must be sure no one else needs the object or is 
using the object. Generally, if someone is using an object, it cannot be deleted. 
However, programs can be deleted unless you use the Allocate Object (ALCOBJ) 
command to allocate the program before it is called. 


Some create commands, such as commands that are used to create programs, 
commands, and device files, have a REPLACE option. This option allows users to 
continue using the old version of a previously replaced object. The system stores 
the old versions of these re-created objects in library QRPLOBJ. 


You should be careful of deleting objects that exist in the system libraries. These 
objects are necessary for the system to perform properly. 


On most delete commands, you can specify a generic name in place of an object 
name. Before using a generic delete, you may want to specify the generic name by 
using the DSPOBJD command to verify that the generic delete will delete only the 
objects you want to delete. See g a 2 07 for 
more information on specifying objects generically. 
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For information about deleting libraries, see (Dele 


Allocating Resources 


Objects are allocated on the system to guarantee integrity and to promote the 
highest possible degree of concurrency. An object is protected even though several 
operations may be performed on it at the same time. For example, an object is 
allocated so that two users can read the object at the same time or one user can 
only read the object while another can read and update the same object. 


OS/400 allocates objects by the function being performed on the object. For 
example: 


* Ifa user is displaying or dumping an object, another user can read the object. 


* If a user is changing, deleting, renaming, or moving an object, no one else can 
use the object. 


* If a user is saving an object, someone else can read the object, but not update or 
delete it; if a user is restoring the object, no one else can read or update the 
object. 


* If a user is opening a database file for input, another user can read the file. If a 
user is opening a database file for output, another user can update the file. 


* If a user is opening a device file, another user can only read the file. 


Generally, objects are allocated on demand; that is, when a job step needs an 
object, it allocates the object, uses the object, and deallocates the object so another 
job can use it. The first job that requests the object is allocated the object. In your 
program, you can handle the exceptions that occur if an object cannot be allocated 
by your request. (See Chapter 7 and Chapter 9 for more information on monitoring 
for messages or your high-level language reference manual for information on 
handling exceptions.) 


Sometimes you want to allocate an object for a job before the job needs the object, 
to ensure its availability so a function that has only partially completed would not 
have to wait for an object. This is called preallocating an object. You can preallocate 
objects using the Allocate Object (ALCOBJ) command. 


Objects are allocated on the basis of their intended use (read or update) and 
whether they can be shared (used by more than one job). The file and member are 
always allocated *SHRRD and the file data is allocated with the level of lock 
specified with the lock state. A lock state identifies the use of the object and 
whether it is shared. The five lock states are (parameter values given in 
parentheses): 


* Exclusive (*EXCL). The object is reserved for the exclusive use of the requesting 
job; no other jobs can use the object. However, if the object is already allocated 
to another job, your job cannot get exclusive use of the object. This lock state is 
appropriate when a user does not want any other user to have access to the 
object until the function being performed is complete. 


* Exclusive allow read (*“EXCLRD). The object is allocated to the job that requested 
it, but other jobs can read the object. This lock is appropriate when a user wants 
to prevent other users from performing any operation other than a read. 


* Shared for update (*“SHRUPD). The object can be shared either for update or 
read with another job. That is, another user can request either a shared-for-read 


138 0S/400 CL Programming V5R2 


lock state or a shared-for-update lock state for the same object. This lock state is 
appropriate when a user intends to change an object but wants to allow other 
users to read or change the same object. 

* Shared no update (*SHRNUP). The object can be shared with another job if the 
job requests either a shared-no-update lock state, or a shared-for-read lock state. 
This lock state is appropriate when a user does not intend to change an object 
but wants to ensure that no other user changes the object. 

* Shared for read (*SHRRD). The object can be shared with another job if the user 
does not request exclusive use of the object. That is, another user can request an 
exclusive-allow-read, shared-for-update, shared-for-read, or shared-no-update 
lock state. 


Note: The allocation of a library does not restrict the operations that can be 
performed on the objects within the library. That is, if one job places an 
exclusive-allow-read or shared-for-update lock state on a library, other jobs 
can no longer place objects in or remove objects from the library; however, 
the other jobs can still update objects within the library. 


The following table shows the valid lock state combinations for an object: 


Table 5. Valid Lock State Combinations 


If One Job Obtains This Lock State: Another Job Can Obtain This Lock State: 
*EXCL None 

*EXCLRD *SHRRD 

*SHRUPD *SHRUPD or *SHRRD 

*SHRNUP *SHRNUP or *SHRRD 

*SHRRD *EXCLRD, *SHRUPD, *SHRNUP, or *SHRRD 


You can specify all five lock states (“EXCL, *EXCLRD, SHRUPD, SHRNUP, and 


SHRRD) for most object types. this does not apply to all object types. Object types 
that cannot have all five lock states specified are listed in the following table with 


valid lock states for the object type: 
Table 6. Valid Lock States for Specific Object Types 


Object Type *EXCL *EXCLRD *SHRUPD *SHRNUP *SHRRD 
Device x 

description 

Library x x x x 
Message queue x x 
Panel group x x 

Program x x x 
Subsystem x 

description 


To allocate an object, you must have object existence authority, object management 
authority, or operational authority for the object. Allocated objects are 
automatically deallocated at the end of a routing step. To deallocate an object at 
any other time, use the Deallocate Object (DLCOBJ) command. 
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You can allocate a program before it is called to protect it from being deleted. To 
prevent a program from running in different jobs at the same time, an exclusive 
lock must be placed on the program in each job before the program is called in any 
job. 


You cannot use the ALCOBJ or DLCOBJ commands to allocate an APPC device 
description. 


The following example is a batch job that needs two files members for updating. 
Members from either file can be read by another program while being updated, 
but no other programs can update these members while this job is running. The 
first member of each file is preallocated with an exclusive-allow-read lock state. 
//JOB JOBD (ORDER) 

ALCOBJ OBJ((FILEA *FILE *EXCLRD) (FILEB *FILE *EXCLRD)) 


CALL PROGX 
//ENDJOB 


Objects that are allocated to you should be deallocated as soon as you are finished 
using them because other users may need those objects. However, allocated objects 
are automatically deallocated at the end of the routing step. 


If the first members of FILEA and FILEB had not been preallocated, the 
exclusive-allow-read restriction would not have been in effect. When you are using 
files, you may want to preallocate them so that you are assured they are not 
changing while you are using them. 


Note: If a single object has been allocated more than once (by more than one 
allocate command), a single DLCOBJ command will not completely 
deallocate that object. One deallocate command is required for each allocate 
command. 


It is not an error if the DLCOBJ command is issued against an object where you do 
not have a lock or do not have the specific lock state requested to be allocated. 


You can change the lock state of an object, as the following example shows: 


PGM 

ALCOBJ OBJ((FILEX *FILE *EXCL)) WAIT(0) 
CALL PGMA 

ALCOBJ OBJ((FILEX *FILE *EXCLRD)) 
DLCOBJ OBJ((FILEX *FILE *EXCL)) 

CALL PGMB 

DLCOBJ OBJ((FILEX *FILE *EXCLRD)) 
ENDPGM 


File FILEX is allocated exclusively for PGMA, but FILEX is allocated as 
exclusive-allow-read for PGMB. 


You can use record locks to allocate data records within a file. You can also use the 
WAITFILE parameter on a Create File command to specify how long your program 
is to wait for that file before a time-out occurs. 


The WAITRCD parameter on a Create File command specifies how long to wait for 


a record lock. The DFTWAIT parameter on the Create Class (CRTCLS) command 
specifies how long to wait for other objects. For a discussion of the WAITRCD 


sceieiee caste a ee ee 
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Displaying the Lock States for Objects 


You can use the Work with Object Locks (WRKOBJLCK) command or the Work 
with Job (WRKJOB) command to display the lock states for objects. 


The WRKOBJLCK command displays all the lock state requests in the system for a 
specified object. It displays both the held locks and the locks being waited for. For 
a database file, the WRKOBJLCK command displays the locks at the file level (the 
object level) but not at the record level. For example, if a database file is open for 
update, the lock on the file is displayed, but the lock on any records within the file 
is not. Locks on database file members can also be displayed using the 
WRKOBJLCK command. 


If you use the WRKJOB command, you can select the locks option on the Display 
Job menu. This option displays all the lock state requests outstanding for the 
specified active job, the locks being held by the job, and the locks for which the job 
is waiting. However, if a job is waiting for a database record lock, this does not 
appear on the object locks display. 


The following command displays all the lock state requests in the system for the 
logical file ORDFILL: 


WRKOBJLCK OBJ(QGPL/ORDFILL) OBJTYPE(*FILE) 


The resulting display is: 
Ve 


Work with Object Locks 4 
System: SYSTEMO1 
Object: ORDFILL Library:  QGPL Type: *FILE-LGL 
Type options, press Enter. 
4=End job 5=Work with job 8=Work with job locks 
Opt Job User Lock Status Scope Thread 
WORKST04 QSECOFR *SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
*SHRRD HELD *JOB 
More... 
F3=Exit F5=Refresh F6=Work with member locks  F12=Cancel 
Ne e 
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Chapter 5. Working with Objects in CL Procedures and 
Programs 


Accessing Objects in CL Programs 


Rules that refer to objects in CL program commands and procedures are the same 
as objects in commands that are processed individually (not within a program). 
Object names can be either qualified or unqualified. Locate an unqualified object 
name through a search of the library list. 


Most objects referred to in CL procedures and programs are not accessed until the 
command referring to them is run. To qualify the name (library/name)of an object, it 
must be in the specified library when the command that refers to it runs. However, 
the object does not have to be in that library at the creation of the program. This 
means that most objects can be qualines in CL source statements that are simply 


You can avoid this run-time consideration for all objects if you do not qualify 
object names on CL source statements, but refer to the library list (*LIBL/name) 
instead. If you refer to the library list at compile time, the object can be in any 
library on the library list at command run time. This is possible providing you do 
not have duplicate-name objects in different libraries. If you use the library list, 
you can move the object to a different library between procedure creation and 
command processing. 


Objects do not need to exist until the command that refers to them runs. Because 
of this, the CL program successfully compiles even though program PAYROLL 
does not exist at compile time: 

PGM /*TESTx/ 


DCL. a: 
MONMSG... 


CALL PGM(QGPL/PAYROLL) 


ENDPGM 


In fact, PAYROLL does not have to exist when activating the program TEST, but 
only when running the CALL command. This creates the called program within 
the calling program immediately prior to the CALL command: 


PGM /*TEST*/ 
DOs. ese 


MONMSG 


CRTCLPGM PGM (QGPL/PAYROLL) 
CALL PGM(QGPL/PAYROLL) 
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ENDPGM 


Note that for create commands, such as (CRTCLPGM) or (CRTDTAARA), the 
object that is accessed at compile or run time is the create command definition, not 
the created object. If you are using a create command, the create command 
definition must be in the library that is used to qualify the command at compile 
time. (Alternately, it must be in a library on the library list if you used *LIBL.) 


Exceptions: Accessing Command Definitions, Files, and 
Procedures 


Two requirements exist for creating a CL program from source statements that 
refer to command definitions or files. 


* The objects must exist at creation time of the program. 
* The objects must exist when the command that refers to them runs. 


This means that if you use the Declare File (DCLF) command, you must create the 
file before creating a program that refers to the file. 


Accessing Command Definitions 

Access to the command definitions occurs during program creation time and at 
command run time. To allow for syntax checking, the command must exist during 
the creation of a program that uses it. If it is qualified at creation time, the 
command needs to exist in the library referred to during creation, and in the same 
library when processed. If it is not library-qualified, it must be in some library on 
the library list during creation time and at run time. 


The command name should be qualified in the program: 


* When the command’s definition will not be accessible through the library list 
while the program is running. 


* When multiple command definitions exist with the same name if expecting a 
specific instance of the command at run time. 


The name of the command must be the same when the program runs as when the 
system created it. An error occurs if the command name changes after creating a 
program that refers to that command. This is because the program cannot find the 
command when it runs. However, if a default changes for a parameter on a 
command, the new default is used when that command runs. For more detail on 
attributes that you may change on a command without having to re-create the 
command, see the Change Command (CHGCMD) command description in the CL 
topic of the Programming category in the iSeries Information Center. 


Accessing Files 

The compiler accesses files when compiling a program module that has a Declare 
File (DCLF) command. The file must exist when compiling a CL module or OPM 
program that uses it. The file does not have to exist when creating a program or 
service program that uses the module. 


Enter Data Description Specifications (DDS) into a source file before creating it. 
The DDS describes the record formats and the fields within the records. 
Additionally, the system compiles this information to create the file object through 
the Create Display File (CRTDSPF) command. 
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Note: You can create other types of files from DDS, and each type has its own 
command: Create Physical File (CRITPF) and Create Logical File (CRTLF) are 
two that create files that you can use in CL programs and procedures. 


The fields that are described in the DDS can be input or output fields (or both). 
The system declares the fields in the CL program or procedure as variables when it 
compiles a program or module. The program manipulates data from display 
through these variables. 


If you do not use DDS to create a physical file, the system declares a CL variable 
to contain the entire record. This variable has the same name as the file, and its 
length is the same as the record length of the file. 


CL programs and procedures cannot manipulate data in any types of files other 
than display files and database files, except with specific CL commands. 


Deletion of the DDS after creating the file is possible but not recommended. You 
can delete the file after the system compiles the CL program or module that refers 
to the file. This is true provided the file exists when the command referring to it, 
such as a Receive File (RCVF), is processed in the program. 


The rules on qualified names that are described here for command definitions also 


nape to files. For more details on files, see king 


Accessing Procedures 

A procedure that is specified by Call Bound Procedure (CALLPRC), does not have 
to exist at the time a module that refers to it is created. The system requires the 
existence of the procedure in order to create a program or service program that 
uses the procedure. The called procedure may be: 


* In a module that is specified on the MODULE parameter on the Create Program 
(CRTPGM) or CRTSRVPGM command. 

* Ina service program that is specified on the BNDSRVPGM parameter. The 
service program must be available at run time. 

* Ina service program or module that is listed in a binding directory that is 
specified on the BNDDIR parameter of the CRTPGM command or CRTSRVPGM 
command. The binding directory and modules do not have to be available at 
run time. 


Checking for the Existence of an Object 


Before attempting to use an object in a program, check to determine if the object 
exists and if you have the authority to use it. This is useful when a function uses 
more than one object at one time. 


To check for the existence of an object, use the Check Object (CHKOBJ) command. 
You can use this command at any place in a procedure or program. The CHKOBJ 
command has the following format: 


CHKOBJ OBJ(library-name/object-name) OBJTYPE(object-type) 
Other optional parameters allow object authorization verification. If you are 


checking for authorization and intend to open a file, you should check for both 
operational and data authority. 
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When this command runs, the system sends messages to the program or procedure 
to report the result of the object check. You can monitor for these messages and 
handle them as you wish. For example: 

CHKOBJ OBJ(OELIB/PGMA) OBJTYPE(*PGM) 


MONMSG MSGID(CPF9801) EXEC(GOTO NOTFOUND) 
CALL OELIB/PGMA 


NOTFOUND: CALL FIX001 /*PGMA Not Found Routinex/ 
ENDPGM 


In this example, the MONMSG command checks only for the object-not-found 
escape message. For a list of all the messages which the CHKOBJ command may 


The CHKOBJ command does not allocate an object. For many application uses the 
check for existence is not an adequate function, the application should allocate the 
object. The Allocate Object (ALCOBJ) command provides both an existence check 
and allocation. 


Use the Check Tape (CHKTAP) or Check Diskette (CHKDKT) command to ensure 
that a specific tape or diskette is placed on the drive and ready. These commands 
also provide an escape message that you can monitor for in your CL program. 


Working with Files in CL Procedures 


Two types of files are supported in CL procedures and programs, display files and 
database files. You can send a display to a work station and receive input from the 
work station for use in the procedure or program, or you can read data from a 
database file for use in the procedure or program. 


Note: Database files are made available for use within the CL procedure or 
program through the DCLF and RCVF commands. 


To use a file in a CL procedure or program, you must: 


* Format the display or database record, identifying fields and conditions which 
you enter as DDS source. The use of DDS is not required for a database file. 

* Create the file using the Create Display File (CRTDSPF) command, Create 
Physical File (CRTPF) command, or Create Logical File (CRTLF) command. 
Subfiles (except for message subfiles) are not supported by CL procedures and 
programs. 

* For database files, add a member to the file using the Add Physical File Member 
(ADDPEM) command or Add Logical File Member (ADDLFM) command. This 
is not required if a member was added by the CRTPF or CRTLF commands. The 
file must have a member when the procedure or program is processed, but does 
not need to have a member when the procedure or program is created. 

* Refer to the file in the CL procedure using the DCLF command, and refer to the 
record format on the appropriate data manipulation CL commands in your CL 
source. 

* Create the CL module. 


* Create the program or service program. 
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Only one display or database file can be referred to in a CL procedure. The 
support for database files and display files is similar as the same commands are 
used. However, there are a few differences, which are described here. 


* The following statements apply only to database files used with CL procedures 
and programs: 


Only database files with a single record format may be used by a CL 
procedure or program. 


The file may be either a physical or logical file, and a logical file may be 
defined over multiple physical file members. 


Only input operations, with the RCVF command, are allowed. The SNDE, 
SNDRCVE, ENDRCV, WAIT and DEV parameters on the RCVF command are 
not allowed for database files. 


DDS is not required to create a physical file which is referred to in a CL 
procedure or program. If DDS is not used to create a physical file, the file has 
a record format with the same name as the file, and there is one field in the 
record format with the same name as the file, and with the same length as the 
record length of the file (RCDLEN parameter of the CRTPF command). 


The file need not have a member when it is created for the module or 
program. It must, however, have a member when the file is processed by the 
program. 


The file is opened for input only when the first RCVF command is processed. 
The file must exist and have a member at that time. 


The file remains open until the procedure or OPM program returns or when 
the end of file is reached. When end of file is reached, message CPF0864 is 
sent to the CL procedure or program, and additional operations are not 
allowed for the file. The procedure or program should monitor for this 
message and take appropriate action when end of file is reached. 


* The following statements apply only to display files used with CL procedures 
and programs: 


Display files may have up to 99 record formats. 

All data manipulation commands (SNDF, SNDRCVF, RCVF, ENDRCV and 
WAIT) are allowed for display files. 

The display file must be defined with the DDS. 

The display file is opened for both input and output when the first SNDF, 
SNDRCVF, or RCVF command is processed. The file remains open until the 
procedure or OPM program returns. 


Note: The open does not occur for both types of files until the first send or receive 


occurs. Because of this, the file to be used can be created during the 
procedure or program and an override can be performed before the first 
send or receive. 


The format for the display is identified as a record format in DDS. Each record 
format may contain fields (input, output, and input/output), conditions/ indicators, 
and constants. Several record formats can be entered in one display file. The 
display file name, record format name, and field names should be unique, because 
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other HLLs may require it, even though CL procedures and programs do not. 
Display Display File DSPFILE 
<+——_ RCDFMT1 


Fieldl Keyword 
Field2 Constant 


RCDFMT2 
Display Field3 
Field4 


RBAFN504-0 


book or the Screen Design Aid (SDA) to enter DDS source for records and fields i in 
the display file. See the 


ACL procedure or program can use several commands, called data manipulation 
commands. These commands let you refer to a display file to send data to and 
receive data from device displays. These commands also allows you to refer to a 
database file to read records from a database file. These commands are: 


* Declare File (DCLF). Defines a display or database file to be used in a procedure 
or program. The fields in the file are automatically declared as variables for use 
in the procedure or program. 

* Send File (SNDF). Sends data to the display. 

* Receive File (RCVF). Receives data from the display or database. 

* Send/Receive File (SGNDRCVF). Sends data to the display; then asks for input 
and, optionally, receives data from the display. 

* Override with Display File (OVRDSPF). Allows a run-time override of a file 
used by a procedure or program with a display file. 

* Override with Database File (OVRDBF). Allows a run-time override of a file 
used by a procedure or program with a database file. 


These commands let a running program communicate with a device display using 
the display functions provided by DDS, and to read records from a database file. 
DDS provides functions for writing menus and performing basic 
application-oriented data requests that are characteristic of many CL applications. 


CL Program DSPFILE Display 
PGM : RCDFMT (A) 
DCLF DSPFILE ——> : |g 

M 
SNDF RCDFMT (A) T 

(A) 

DDS 


RBAFNSO05-0 


The fields on the display or in the record are identified in the DDS for the file. In 
order for the CL procedure or program to use the fields, the file must be referred 
to in the CL procedure or program by the DCLF command. This reference causes 
the fields and indicators in the file to be declared automatically in your procedure 
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or program as variables. You can use these variables in any way in CL commands; 
however, their primary purpose is to send information to and receive information 
from a display. The DCLF command is not used at run time. 


The format of the display and the options for the fields are specified in the device 
file and controlled through the use of indicators. Up to 99 indicator values can be 
used with DDS and CL support. Indicator variables are declared in your CL 
procedure or program in the form of logical variables with names &INO1 through 
&IN99 for each indicator that appears in the device file record formats referred to 
on the DCLF command. Indicators let you display fields and control data 
management display functions, and provide response information to your 
procedure or program from the device display. Indicators are not used with 
database files. 


Referring to Files in a CL Procedure 


Files are accessed during compiling of DCLF commands when CL modules and 
programs are created so that variables can be declared for each field in the file. 


If you have qualified the name of the file at compile time, the file must be in that 
library at run time. If you have used the library list at compile time, the file must 
be in a library on the library list at run time. 


Opening and Closing Files in a CL Procedure 


When you use CL support, you can refer to only one file in a procedure or OPM 
program. The file referred to is implicitly opened when you do your first send, 
receive, or send/receive operation. An opened display file remains open until the 
procedure or OPM program in which it was opened returns or transfers control. 
An opened database file is closed when end of file is reached, or when the 
procedure or OPM program in which it was opened returns or transfers control. 
Once a database file has been closed, it cannot be opened again during the same 
call of the procedure or OPM program. 


When a database file opens, the first member in the file will open, unless you 
previously used an OVRDBF command to specify a different member (MBR 
parameter). If a procedure or OPM program ends because of an error, the files 
close. A file remains open until the procedure or OPM program in which that file 
was opened ends. Because of this, you have an easy way to share open data paths 
between running procedures and programs. You can open a file in one procedure 
or program. Then the file can share its open data path with another procedure or 
program under either of the following conditions: 


* The file was created with or has been changed to have the SHARE(*YES) 
attribute. 


* An override for that file by specifying SHARE(*YES) is in effect. 


You can share files in this way between any two procedures or programs. Use 
online help for a detailed description of the function available when the system 
shares open data paths. Additionally, IBM provides a description of the SHARE 
parameter on the CRTDSPF, CRTPF, and CRTLF commands online. Refer to the CL 
section of the Programming category in the iSeries Information Center. A display 
file opened in a CL procedure or OPM program always opens for both input and 
output. A database file opened in a CL procedure or OPM program opens for input 
only. 
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Do not specify LVL(*CALLER) on the Reclaim Resources (RCLRSC) command in 
CL procedures and programs using files. If you specified LVL(*CALLER), all files 
opened by the procedure or OPM program would be immediately closed, and any 
attempt to access the file would end abnormally. 


Declaring a File 


The Declare File (DCLF) command is used to declare a display or database file to 
your CL procedure or program. The DCLF command cannot be used to declare 
files such as tape, diskette, printer, and mixed files. Only one DCLF command is 
allowed in a CL procedure or OPM program. The DCLF command has the 
following parameters: 


DCLF FILE(library-name/file-name) 
RCDFMT (record-format-names) 


Note that the file must exist before the module or program is compiled. 


If you are using a display file in your procedure or program, you may have to 
specify input and output fields in your DDS. These fields are handled as variables 
in the procedure or program. When processing a DCLF command, the CL compiler 
declares CL variables for each field and option indicator in each record format in 
the file. For a field, the CL variable name is the field name preceded by an 
ampersand (&). For an option indicator, the CL variable name is the indicator that 
is preceded by &IN. 


For example, if a field named INPUT and indicator 10 are defined in DDS, the 
DCLF command automatically declares them as &INPUT and &IN10. This 
declaration is performed when the CL module or program is compiled. Up to 50 
record format names can be specified on one command, but none can be variables. 
Only one record format may be specified for a database file. 


If the following DDS were used to create display file CNTRLDSP in library 


MCGANN: 
lasehites Loesteaec2eenstedegde nates ethos esPiard Beene eeeOscdetie eds cacteas8 
A R MASTER 
A CAQ1(01 'F1 RESPONSE') 
A TEXT 300 2 4 
A RESPONSE 15 1 8 4 BLINK 
A 
A 


Three variables, &INO1, & TEXT, and &RESPONSE, would be available from the 
display file. In a CL procedure referring to this display file, you would enter only 
the DCLF source statement: 


DCLF MCGANN/CNTRLDSP 


The compiler will expand this statement to individually declare all display file 
variables. The expanded declaration in the compiler list looks like this: 
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500- DCLF MCGANN/CNTRLDSP 
QUALIFIED FILE NAME 'MCGANN ' —'CNTRLDSP 


RECORD FORMAT NAME = ‘'MASTER ; 


CL VARIABLE TYPE LENGTH PRECISION (IF *DEC) 


&INO1 *LGL 1 
&TEXT *CHAR 300 
&RESPONSE *CHAR 15 


Sending and Receiving Data with a Display File 


The only commands you can use with a display file to send or receive data in CL 
procedures and programs are the SNDF, RCVF, and SNDRCVF commands. 


The system formats the content of the variables associated with the output or 
output/input fields in the record format when you run a SNDF command. 
Additionally the system sends it to the display device. This is similar to when you 
run a RCVF command. The values of the fields associated with input or 
output/input fields in the record format on the display are placed in the 
corresponding CL variables. 


The SNDRCVF command sends the contents of the CL variables to the display. The 
command then performs the equivalent of a RCVF command to obtain the updated 
fields from the display. Note that CL does not support zoned decimal numbers. 
Consequently, fields in the display file that are defined as zoned decimal, cause 
*DEC fields to be defined in the CL procedure or program. *DEC fields are 
internally supported as packed decimal, and the CL commands convert the packed 
and zoned data types as required. Fields that overlap in the display file because of 
coincident display positions result in separately defined CL variables that do not 
overlap. You cannot use record formats that contain floating point data in a CL 
procedure or program. 


Note: If a SNDRCVF or RCVF command for a work station indicates WAIT(*NO), 
then the system uses the WAIT command to receive data. The same is true if 
a SNDF command is issued using a record format containing the INVITE 
DDS keyword. 


Except for message subfiles, any attempt to send or receive subfile records causes 
run-time errors. Most other functions specified for display files in DDS are 
available; some functions (such as using variable starting line numbers) are not. 
For more information on messages and subfiles in CL procedures and programs, 
see 


The following example shows the steps required to create a typical operator menu 


and to send and receive data using the SNDRCVF command. The menu looks like 
this: 
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Operator Menu 
1. Accounts Payable 
2. Accounts Receivable 
90. Signoff 


Option: 


XX 7 


First, enter the following DDS source. The record format is MENU, and OPTION is 
an input-capable field. The OPTION field uses DSPATR(MDT). This causes the 
system to check this field for valid values even if the operator does not enter 
anything. 


1 2'Operator Menu' 
3 4'1. Accounts Payable' 
5 4'2. Accounts Receivable' 
5 4'90. Signoff' 
7 2'Option' 
OPTION 2Y 01 + 2VALUES(1 2 90) DSPATR(MDT) 


rPrrrrrrr,r 


Enter the CRTDSPF command to create the display file. In CL programming, the 
display file name (INTMENU) can be the same as the record format name 
(MENU), though this is not true for some other languages, like RPG for OS/400. 


The display file could also be created using the Screen Design Aid (SDA) utility. 
Next, enter the CL source to run the menu. 


The CL source for this menu is: 


PGM /* OPERATOR MENU */ 
DCLF INTMENU 
BEGIN: | SNDRCVF RCDFMT (MENU) 
IF COND(&OPTION *EQ 1) THEN(CALL ACTSPAYMNU) 
IF COND(&OPTION *EQ 2) THEN(CALL ACTSRCVMNU) 
IF COND(&OPTION *EQ 90) THEN(SIGNOFF) 
GOTO BEGIN 
ENDPGM 


When this source is compiled, the DCLF command automatically declares the 
input field OPTION in the procedure as a CL variable. 


The SNDRCVF command defaults to WAIT(*YES); that is, the program waits until 
input is received by the program. 


Writing a CL Program to Control a Menu 


The following example shows how a CL procedure can be written to display and 


control a menu. See the [Applica a 2 book for another 
method of creating and controlling menus. 
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This example shows a CL procedure, ORDO040C, that controls the displaying of the 


order department general menu and determines which HLL procedure to call 
based on the option selected from the menu. The procedure shows the menu at 
display station. 


The order department general menu looks like this: 
Order Dept General Menu 


1 Inquire into customer file 

2 Inquire into item file 

3 Customer name search 

4 Inquire into orders for a customer 
5 Inquire into an existing order 

6 Order entry 

8 End of menu 


Ss 


the 


The DDS for the display file ORDO40C looks like this: 


* MENU ORDO40CD ORDER DEPT GENERAL MENU 


R MENU TEXT('General Menu') 

1 2'Order Dept General Menu' 

3 3'1 Inquire into customer file' 

4 3'2 Inquire into item file' 

5 3'3 Customer name search' 

6 3'4 Inquire into orders for a custom+ 
er' 
3'5 Inquire into existing order' 
3'6 Order Entry' 

9 2'98 End of menu' 
11 2'Option' 
RESP 2Y001 11 10VALUES(1 2 3 4 5 6 98) 
DSPATR (MDT) 


rPrrrrrrrrrrrrrrrp,p 


The source procedure for ORD040C looks like this: 


PGM /* ORDO40C Order Dept General Menu */ 
DCLF FILE(ORDO40CD) 
START: SNDRCVF RCDFMT (MENU) 
IF (&RESP=1) THEN(CALLPRC CUS210) 
/* Customer inquiry */ 
ELSE + 
IF (&RESP=2) THEN(CALLPRC ITM210) 
/*xItem inquiry*/ 
ELSE + 
IF (&RESP=3) THEN(CALLPRC CUS220) 
/* Cust name search */ 
ELSE + 
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IF (&RESP=4) THEN(CALLPRC ORD215) 
/* Orders by cust */ 
ELSE + 
IF (&RESP=5) THEN(CALLPRC ORD220) 
/* Existing order */ 
ELSE + 
IF (&RESP=6) THEN(CALLPRC ORD410C) 
/* Order entry */ 
ELSE + 
IF (&RESP=98) THEN(RETURN) 
/* End of Menu */ 
GOTO START 
ENDPGM 


The DCLF command indicates which file contains the field attributes the system 
needs to format the order department general menu when the SNDRCVF 
command is processed. The system automatically declares a variable for each field 
in the record format in the specified file if that record format is used in an SNDF, 
RCVF, or SNDRCVF command. The variable name for each field automatically 
declared is an ampersand (&) followed by the field name. For example, the 
variable name of the response field RESP in ORDO040C is &RESP. 


Other notes on the operation of this menu: 
The SNDRCVF command is used to send the menu to the display and to 
receive the option selected from the display. 
If the option selected from the menu is 98, ORDO40C returns to the procedure 
that called it. 
The ELSE statements are necessary to process the responses as mutually 
exclusive alternatives. 


Note: This menu is run using the CALL command. See the 
eh book for a discussion of those menus run using the GO 


command. 


Overriding Display Files in a CL Procedure 


You can use the Override with Display File (OVRDSPF) command to replace the 
display file named in a CL procedure or program or to change certain parameters 
of the existing display file. This may be especially useful for files that have been 
renamed or moved since the module or program was compiled. 


The initial parameters of the OVRDSPF command are: 


OVRDSPF FILE(overridden-file-name) TOFILE(new-file-name) 
DEV (device-name) 


The OVRDSPF command is valid for a file referred to by a CL procedure or 
program only if the file specified on the DCLF command was a display file when 
the module or program was created. The file used when the program is run must 
be of the same type as the file referred to when the module or program was 
created. 


You must run the OVRDSPF command before opening the file that is being 
overridden. An open is caused by the first use of a send or receive command. The 
system overrides the file on finding any of the following conditions: 


* A procedure or program that contains the OVRDSPF command opens the file. 


* The file opens in another procedure which transfers control by using the 
CALLPRC command. 
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* The file opens in another program which transfers control by using the CALL 
command. 


When you override to a different file, only those record format names referred to 
on the SNDF, RCVE, or SNDRCVF command need to be in the overriding file. In 
the following illustration, display file FILEY does not need record format TWO or 


THREE. 
Display Files CL Program 
MCGANN/FILEX 

RCDFMT ONE PGM 

Field 1 DCLF MCGANN/FILEX 

RCDFMT TWO 

Field 2 

RCDFMT THREE : 

Field 3 OVRDSPF FILE(FILEX) TOFILE(FILEY) 
MCGANN/FILEY : 
RCDFMT ONE SNDF RCDFMT (ONE) 
Field 1 

ENDPGM 


RBAFN531-0 


You should make sure that the record format referred to names of the original file 
and the overriding files have the same field definitions and indicator names in the 
same order. You may get unexpected results if you specify LVLCHK(*NO). 


Another consideration has to do with the DEV parameter on the SNDF, RCVF, and 
SNDRCVF commands when an OVRDSPF command is applied. If *FILE is 
specified on the DEV parameter of the RCVF, SNDF, or SNDRCVF command, the 
system automatically directs the operation to the correct device for the overridden 
file. If a specific device is specified on the DEV keyword of the RCVE, SNDF, or 
SNDRCVF command, one of the following may occur: 


* If a single device display file is being used, an error will occur if the display file 
is overridden to a device other than the one specified on the RCVF, SNDF, or 
SNDRCVF command. 


* Ifa multiple device display file is being used, an error will occur if the device 
specified on the RCVF, SNDF, or SNDRCVF command is not among those 
specified on the OVRDSPF command. 


Working with Multiple Device Display Files 


The normal mode of operation on a system is for the work station user to sign on 
and become the requester for an interactive job. Many users can do this at the 
same time, because each will use a logical copy of the procedure, including the 
display file in the procedure. Each requester calls a separate job in this kind of use. 
This is not considered to be multiple device display use. 


A multiple device display configuration occurs when a single job called by one 
requester communicates with multiple display stations through one display file. 


While only one display file can be handled by a CL procedure, the display file, or 


Chapter 5. Working with Objects in CL Procedures and Programs 155 


different record formats within it, can be sent to several device displays. 
Commands used primarily with multiple device display files are: 


* End Receive (ENDRCV). This command cancels requests for input that have not 
been satisfied. 


* Wait (WAIT). Accepts input from any device display from which user data was 
requested by one or more previous RCVF or SNDRCVF commands when 
WAIT(*NO) was specified on the command, or by one or more previous SNDF 
commands to a record format containing the INVITE DDS keyword. 


If you use a multiple device display file, the device names must be specified on the 
DEV parameter on the CRTDSPF command when the display file is created, on the 
CHGDSPF command when the display file is changed, or on an override 
command, and the number of devices must be less than or equal to the number 
specified on the MAXDEV parameter on the CRTDSPF command. 


Multiple device display configurations affect the SNDRCVF and the RCVF 
commands and you may need to use the WAIT or ENDRCV commands. When an 
RCVF or SNDRCVF command is used with multiple display devices, the default 
value WAIT(*YES) prevents further processing until an input-capable field is 
returned to the program from the device named on the DEV parameter. Because 
the response may be delayed, it is sometimes useful to specify WAIT(*NO), thus 
letting your procedure or program continue running other commands before the 
receive operation is satisfied. 


If you use an RCVF or SNDRCVF command and specify WAIT(*NO), the CL 
procedure or program continues running until a WAIT command is processed. 


Using a SNDF command with a record format which has the DDS INVITE 
keyword is equivalent to using a SNDRCVF command with WAIT(*NO) specified. 
The DDS INVITE keyword is ignored for SNDRCVF and RCVF commands. 


The WAIT command must be issued to access a data record. If no data is available, 
processing is suspended until data is received from a device display or until the 
time limit specified in the WAITRCD parameter for the display file on the 
CRTDSPF, CHGDSPFE, or OVRDSPF commands has passed. If the time limit passes, 
message CPF0889 is issued. 


The WAIT will also be satisfied by the job being canceled with the controlled 
option on the ENDJOB, ENDSYS, PWRDWNSYS, and ENDSBS commands. In this 
case, message CPF0888 is issued and no data is returned. If a WAIT command is 
issued without a preceding receive request (such as RCVF . .. WAIT(*NO)), a 
processing error occurs. 
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A typical multiple device display configuration (with code) might look like this: 


DSPFILE WS2 

SNDF DEV(WS2) RCDFMT(1) 

RCVFDEV(WS2) RCDFMT(1) WAIT(*YES) « FMT 1 > 
SNDRCVF DEV(WS1) RCDFMT(2) WAIT (*NO) WS1 
CALLPROGA EMT? el 

WAIT 


RBAFN506-0 


In the above example, the first two commands show a typical sequence in which 
the default is taken; processing waits for the receive operation from WS2 to 
complete. Because WS2 is specified on the DEV parameter, the RCVF command 
does not run until WS2 responds, even if prior outstanding requests (not shown) 
from other stations are satisfied. 


The SNDRCVF command, however, has WAIT(*NO) specified and so does not wait 
for a response from WS1. Instead, processing continues and PROGA is called. 
Processing then stops at the WAIT command until an outstanding request is 
satisfied by a work station, or until the function reaches time-out. 


The WAIT command has the following format: 
WAIT DEV(CL-variable-name) 


If the DEV parameter is specified, the CL variable name is the name of the device 
that responded. (The default is *NONE.) If there are several receive requests (such 
as RCVF. .. WAIT(*NO)), this variable takes the name of the first device to 
respond after the WAIT command is encountered and processing continues. The 
data received is placed in the variable associated with the field in the device 
display. 


A RCVF command with WAIT(*YES) specified can be used to wait for data from a 
specific device. The same record format name must be specified for both the 
operation that started the receive request and the RCVF command. 


In some cases, several receive requests are outstanding, but processing cannot 
proceed further without a reply from a specific device display. In the following 
example, three commands specify WAIT(*NO), but processing cannot continue at 
label LOOP until WS3 replies: 


PGM 


SNDF DEV(WS1) RCDFMT (ONE) 

SNDF DEV(WS2) RCDFMT (TWO) 

SNDRCVF DEV(WS3) RCDFMT(THREE) WAIT(*NO) 
RCVF DEV(WS2) RCDFMT(TWO) WAIT(*NO) 

RCVF DEV(WS1) RCDFMT(ONE) WAIT(*NO) 
CALL... 
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CALL... 


RCVF DEV(WS3) RCDFMT(THREE) WAIT(*YES) 
LOOP: | WAIT DEV(&WSNAME) 
MONMSG CPFQ882 EXEC(GOTO REPLY) 


GOTO LOOP 
REPLY: CALL... 


ENDPGM 


CL procedures and programs also support the ENDRCV command, which lets you 
cancel a request for input that has not yet been satisfied. A SNDF or SNDRCVF 
command will also cancel a request for input that has not yet been satisfied. 
However, if the data was available at the time the SNDF or SNDRCVF command 
was processed, message CPF0887 is sent. In this case the data must be received 
with the WAIT command or RCVF command, or the request must be explicitly 
canceled with a ENDRCV command before the SNDF or SNDRCVF command can 
be processed. 


Receiving Data from a Database File 


The only command you can use to receive data from a database file is the RCVF 
command. 


When you run a RCVF command, the next record on the file’s access path is read, 
and the values of the fields defined in the database record format are placed in the 
corresponding CL variables. Note that CL does not support zoned decimal or 
binary numbers. Consequently, fields in the database file defined as zoned decimal 
or binary cause *DEC fields to be defined in the CL procedure or program. *DEC 
fields are internally supported as packed decimal, and the RCVF command 
performs the conversion from zoned decimal and binary to packed decimal as 
required. Database files which contain floating point data cannot be used in a CL 
procedure or program. 


When the end of file is reached, message CPF0864 is sent to the procedure or OPM 
program. The CL variables declared for the record format are not changed by the 
processing of the RCVF command when this message is sent. You should monitor 
for this message and perform the appropriate action for end of file. If you attempt 
to run additional RCVF commands after end of file has been reached, message 
CPF0864 is sent again. 


Overriding Database Files in a CL Procedure or Program 


You can use the Override with Database File (OVRDBF) command to replace the 
database file named in a CL procedure or program or to change certain parameters 
of the existing database file. This may be especially useful for files that have been 
renamed or moved since the procedure or program was created. It can also be 
used to access a file member other than the first member. 


The initial parameters of the OVRDBF command are: 


OVRDBF FILE(overridden-file-name) TOFILE(new-file-name) 
MBR (member-name) 
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The OVRDBF command is valid for a file referred to by a CL procedure or 
program only if the file specified in the DCLF command was a database file when 
the module or program was created. The file used when the program was 
processed must be of the same type as the file referred to when the module or 
program was created. 


The OVRDBF command must be processed before the file to be overridden is 
opened for use (an open occurs by the first use of the RCVF command). The file is 
overridden if it is opened in the procedure or OPM program containing the 
OVRDBF command, or if it is opened in another program to which control is 
transferred by the CALL command, or if it is opened in another procedure to 
which control is transferred using the CALLPRC command. 


When you override to a different file, the overriding file must have only one 
record format. A logical file which has multiple record formats defined in DDS 
may be used if it is defined over only one physical file member. A logical file 
which has only one record format defined in the DDS may be defined over more 
than one physical file member. The name of the format does not have to be the 
same as the format name referred to when the program was created. You should 
ensure that the format of the data in the overriding file is the same as in the 
original file. You may get unexpected results if you specify LVLCHK(*NO). 


Referring to Output Files from Display Commands 


A number of the IBM display commands allow you to place the output from the 
command into a database file (QUTFILE parameter). The data in this file can be 
received directly into a CL procedure or program and processed. 


The following CL procedure accepts two parameters, a user name and a library 
name. The procedure determines the names of all programs, files, and data areas in 
the library and grants normal authority to the specified users. 
PGM PARM(&USER &LIB) 
DCL &USER *CHAR 10 
DCL &LIB *CHAR 10 
(1) DCLF QSYS/QADSPOBJ 
(2) DSPOBJD OBJ(&LIB/*ALL) OBJTYPE(*FILE *PGM *DTAARA) + 
OUTPUT(*OUTFILE) OUTFILE(QTEMP/DSPOBJD) 
(3) OVRDBF QADSPOBJ TOFILE(QTEMP/DSPOBJD) 
(4) READ: RCVF 
(5) MONMSG CPFO864 EXEC(RETURN) /* EXIT WHEN END OF FILE REACHED +*/ 
(6) GRTOBJAUT OBJ(&ODLBNM/&ODOBNM) OBJTYPE(&0DOBTP) + 
USER(&USER) AUT(*CHANGE) 
GOTO READ /*GO BACK FOR NEXT RECORD*/ 
ENDPGM 


(1) The declared file, QADSPOBJ in QSYS, is the IBM-supplied file that is used 
by the DSPOBJD command. This file is the primary file which is referred to 
by the command when creating the output file. It is referred to by the CL 
compiler to determine the format of the records and to declare variables 
for the fields in the record format. 


(2) The DSPOBJD command creates a file named DSPOBJD in library QTEMP. 
This file has the same format as file QADSPOBJ. 


(3) The OVRDBF command overrides the declare file (QADSPOBJ) to the file 
created by the DSPOBJD command. 


(4) The RCVF command reads a record from the DSPOBJD file. The values of 
the fields in the record are copied into the corresponding CL variables, 
which were implicitly declared by the DCLF command. Because the 
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OVRDBF command was used, the file QTEMP/DSPOBJD is read instead of 
QSYS/QADSPOB]J (the file QSYS/QADSPOB}J is not read). 


(5) Message CPF0864 is monitored. This indicates that the end of file has been 
reached, so the procedure returns control to the calling procedure. 


(6) The GRTOBJAUT command is processed, using the variables for object 
name, library name and object type, which were read by the RCVF 
command. 
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Chapter 6. Advanced Programming Topics 


This chapter introduces more advanced programming topics, including: 

* Special functions that can be called from high-level language programs 
(including CL programs) 

* Using prompting and the Programmer Menu to enter program source 


See the CL section of the Programming category of the iSeries Information Center 
for information on advanced function command processing. 


This chapter includes General Use Programming Interface (GUPI), which IBM 
makes available for use in customer-written programs. 


Several sample programs are included at the end of the chapter. 


Using the QCAPCMD Program 


The Process Commands (QCAPCMD) application program interface (API) 
performs command analyzer processing on command strings. You can use this API 
to do the following: 


* Check the syntax of a command string prior to running it. 

* Prompt the command and receive the changed command string. 
* Use a command from a high-level language. 

* Display the help for a command. 


See the APIs section of the Programming category of the iSeries Information Center 
for information on the QCAPCMD API. 


Using the QCMDEXC Program 


Execute Command (QCMDEXC) is an IBM-supplied program that runs a single 
command. This command is used to activate another command: 


* From within a high-level language (HLL) program. 
* From within a CL procedure. 


* From a program where it is not known at compile time what command is to be 
run or what parameters are to be used. 


The QCMDEXC program is called from within the HLL or CL procedure or 
program. The command that is to be run is passed as a parameter on the CALL 
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command. 


CL or HLL program QCMDEXC 
-——>| PGM(PARM1 PARM2) 


CALL QCMDEXC(PARM1 PARM2) ‘ 
<————, RETURN 


RBAFN558-0 


After the command runs, control returns to your HLL or CL procedure or program. 


The command runs as if it was not in a program. Therefore, variables cannot be 
used on the command because values cannot be returned by the command to CL 
variables. Additionally, commands that can only be used in CL procedures or 
programs cannot be run by the QCMDEXC program. The format of the call to the 
QCMDEXC program is the following: 


CALL PGM(QCMDEXC) PARM(command command-length) 


Enter the command you wish to run as a character string on the first parameter. 
You must specify the command library. 


CALL PGM(QCMDEXC ) PARM('QSYS/CRTLIB LIB(TEST)' 22) 


Remember that you must enclose the command in apostrophes if it contains 
blanks. The maximum length of the character string is 6000 characters; never count 
the delimiters (the apostrophes ) as part of the string. The length that is specified 
as the second value on the PARM parameter is the length of the character string 
that is passed as the command. Length must be a packed decimal value of length 
15 with 5 decimal positions. 


Thus, to replace a library list, the call to the QCMDEXC program would look like 
this: 

CALL PGM(QCMDEXC) PARM('CHGLIBL LIBL(QGPL NEWLIB QTEMP)' 31) 

It is possible to code this statement into the HLL or CL program to replace the 
library list when the program runs. The QCMDEXC program does not provide 


run-time flexibility when used this way. 


Providing run-time flexibility is accomplished by: 
1. Substituting variables for the constants in the parameter list, and 
2. Specifying the values for the variables in the call to the HLL or CL program. 


For instance: 
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CALL PGM(PGMA) PARM('ADDLIBLE LIB(MYLIB)' 19) 


PGM PARM(&STRING &LENGTH) /* PGMA */ 
DCL &STRING *CHAR LEN(3000) 
DCL &LENGTH *DEC LEN(15 5) 


>—> QCMDEXC 


CALL PGM(QCMDEXC) PARM(&STRING &LENGTH) 
. < 


CHGLIBL... 
END 


RBAFN500-0 


Figure 2. Example of Call PGM 


The command length, passed to the QCMDEXC program on the second parameter, 
is the maximum length of the passed command string. Should the command string 
be passed as a quoted string, the command length is exactly the length of the 
quoted string. Should the command string be passed in a variable, the command 
length is the length of the CL variable. It is not necessary to reduce the command 
length to the actual length of the command string in the variable, although it is 
permissible to do so. 


Not all commands can be run using the QCMDEXC program. The command 
passed on a call to the QCMDEXC program must be valid within the current 
environment (interactive or batch) in which the call is being made. The command 
cannot be one of the following: 


* An input stream control command (BCHJOB, ENDBCHJOB, and DATA) 
* A command that can be used only in a CL program 


IBM has provided online information to help you determine if you can pass a CL 
command on a call to the QCMDEXC program. Refer to the command in the CL 
section of the Programming category in the iSeries Information Center. To find the 
environment in which you can run the command, look at the syntax diagram for 
the command. The small box in the upper right corner of the diagram indicates the 
environment in which you can run the command. For example, JOB: I indicates 
that the command can be run interactively; JOB: B indicates that you can run the 
command in a batch job; Exec indicates that you can run the command with 
QCMDEXC. 


You can precede the CL command with a question mark (?) to request prompting 
or use selective prompting when you call QCMDEXC in an interactive job. 


If an error is detected while a command is being processed through the 

QCMDEXC program, an escape message is sent. You can monitor for this escape 
message in your CL procedure or program using the Monitor Message (MONMSG) 
command. For more information about monitoring for messages, aed and 


If a syntax error is detected, message CPFO0006 is sent. If an error is detected 
during the processing of a command, any escape message sent by the command is 
returned by the QCMDEXC program. You monitor for messages from commands 
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run through the QCMDEXC program in the same way you monitor for messages 
from commands contained in CL procedures and programs. 


See the appropriate HLL reference for information on how HLL programs handle 
errors on calls. 


Using the QCMDEXC Program with DBCS Data 


You can use QCMDEXC to request double-byte character set (DBCS) input data to 
be entered with a command. The command format used for QCMDEXC to prompt 
double-byte data is: 


CALL QCMDEXC (‘command' command-length IGC) 


The third parameter of the QCMDEXC program, IGC, instructs the system to 
accept double-byte data. For example, the following CL program asks a user to 
provide double-byte text for a message. Then the system sends the following 
message: 


PGM 
CALL QCMDEXC ('?SNDMSG' 7 IGC) 
ENDPGM 


An explanation of the system message follows: 


* The ? character instructs the system to present the command prompt for the 
Send Message (SNDMSG) command. 


* The value 7 is the length of the SNDMSG command plus the question mark. 
* The value IGC lets you request double-byte data. 


The following display is shown after running the QCMDEXC program. You can 
use double-byte conversion on this display: 


= 
SEND MESSAGE (SNDMSG) 

TYPE CHOICES, PRESS ENTER. 

MESSAGES MEX 85 ess aee cece ce) seh ay ose este 

TORUS ERAPRO BE Eerepee torent tease nears NAME, *SYSOPR, *ALLACT... 

BOTTOM 

F3=EXIT F4=PROMPT F5=REFRESH F10=ADDITIONAL PARAMETERS F12=CANCEL 

eae TO USE THIS DISPLAY F24=MORE KEYS me 
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Using the QCMDCHK Program 


QCMDCHK is an IBM-supplied program that performs syntax checking for a 
single command, and optionally prompts for the command. The command is not 
run. If prompting is requested, the command string is returned to the calling 
procedure or program with the updated values as entered through prompting. The 
QCMDCHK program can be called from a CL procedure or program or an HLL 
procedure or program. 


Typical uses of QCMDCHK are: 


* Prompt the user for a command and then store the command for later 
processing. 


* Determine the options the user specified. 


* Log the processed command. First, prompt with QCMDCHK, run with 
QCMDEXC, and then log the processed command. 


The format of the call to QCMDCHK is: 
CALL PGM(QCMDCHK) PARM(command command-length) 


The first parameter passed to QCMDCHIK is a character string containing the 
command to be checked or prompted. If the first parameter is a variable and 
prompting is requested, the command entered by the work station user is placed in 
the variable. 


The second parameter is the maximum length of the command string being 
passed. If the command string is passed as a quoted string, the command length is 
exactly the length of the quoted string. If the command string is passed in a 
variable, the command length is the length of the CL variable. The second 
parameter must be a packed decimal value of length 15 with 5 decimal positions. 


The QCMDCHK program performs syntax checking on the command string which 
is passed to it. It verifies that all required parameters are coded, and that all 
parameters have allowable values. It does not check for the processing 
environment. That is, a command can be checked whether it is allowed in batch 
only, interactive only, or only in a batch or interactive CL program. QCEMDCHK 
does not allow checking of command definition statements. 


If a syntax error is detected on the command, message CPF0006 is sent. You can 
monitor for this message to determine if an error occurred on the command. 
Message CPF0006 is preceded by one or more diagnostic messages that identify the 
error. In the following example, control is passed to the label ERROR within the 
program, because the value 123 is not valid for the PGM parameter of the 
CRTCLPGM command. 


CALL QCMDCHK ('CRTCLPGM PGM(QGPL/123)' 22) 
MONMSG CPFO006 EXEC(GOTO ERROR) 


You can request prompting for the command by either placing a question mark 
before the command name or by placing selective prompt characters before one or 
more keyword names in the command string. 


If no errors are detected during checking and prompting for the command, the 
updated command string is placed in the variable specified for the first parameter. 
The prompt request characters are removed from the command string. This is 
shown in the following example: 
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DCL &CMD *CHAR 2000 


CHGVAR &CMD '?CRTCLPGM' 
CALL QCMDCHK (&CMD 2000) 


After the call to the QCEMDCHK program is run, variable &CMD contains the 
command string with all values entered through the prompter. This might be 
something like: 

CRTCLPGM PGM(PGMA) SRCFILE(TESTLIB/SOURCE) USRPRF(*OWNER) 


Note that the question mark preceding the command name is removed. 


When prompting is requested through the QCMDCHK program, the command 
string should be passed in a CL variable. Otherwise, the updated command string 
is not returned to your procedure or program. You must also be sure that the 
variable for the command string is long enough to contain the updated command 
string which is returned from the prompter. If it is not long enough, message 
CPF0005 is sent, and the variable containing the command string is not changed. 
Without selective prompting, the prompter only returns entries that were typed by 
the user. 


The length of the variable is determined by the value of the second parameter, and 
not the actual length of the variable. In the following example, escape message 
CPFO0005 is sent because the specified length is too short to contain the updated 
command, even though the variable was declared with an adequate length. 


DCL &CMD *CHAR 2000 


CHGVAR &CMD '?CRTCLPGM' 
CALL QCMDCHK (&CMD 9) 


If you press F3 or F12 to exit from the prompter while running QCMDCHK, 
message CPF6801 is sent to the procedure or program that called QCMDCHK, and 
the variable containing the command string is not changed. 


If PASSATR(*YES) is specified on the PARM, ELEM, or QUAL command definition 
statement, and the default value is changed using the CHGCMDDFT command, 
the default value is highlighted as though this was a user-specified value and not a 
default value. If a default value of a changed PARM, ELEM, or QUAL command 
definition statement is changed back to its original default value, the default value 
will no longer be highlighted. 


Using Message Subfiles in a CL Program or Procedure 


In CL procedures and programs, message subfiles are the only type of subfiles 
supported. To use subfile message support, run a SNDF or SNDRCVF command 
using the subfile message control record. In the DDS, supply SFLPGMQ data and 
always have SFLINZ active. 


When you use message subfiles in CL procedures and programs, you must name a 
procedure or program. You cannot specify an * for the SFLPGMQ keyword in DDS. 
When you specify a procedure or OPM program name, all messages sent to that 
procedure’s or program’s message queue are taken from the invocation message 
queue and placed in the message subfile. All messages associated with the current 
request are taken from the CALL message queue and placed in the message 
subfile. 
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Message subfiles let a controlling procedure or program display one or more error 
messages. 


Allowing User Changes to CL Commands at Run Time 


With most CL procedures and programs, the work station user provides input to 
the procedure or program by specifying parameter values passed to the procedure 
or program or by typing into input-capable fields on a display prompt. 


You can also prompt the work station user for input to a CL procedure or program 
in the following ways: 


* If you enter a ? before the CL command in the CL procedure or program source, 
the system displays a prompt for the CL command. Parameter values you have 
already specified in your procedure or program are filled in and cannot be 


changed by the work station user. See g 
“ESR SET | ee 


* If you call the QCMDEXC program and request selective prompting, the system 
displays a prompt for a CL command, but you need not specify in the CL 
program source which CL command is to be used _at processing time. For more 
information on the QCMDEXC program, see 


Using the Prompter within a CL Procedure or Program 


You can request prompting within the interactive processing of a CL procedure or 
program. For example, the following procedure can be compiled and run: 


PGM 
?DSPLIB 


ENDPGM 


In this case, the prompt for the Display Library (DSPLIB) command appears on the 
display during processing of the program. Processing of the DSPLIB command 
waits until you have entered values for required parameters and pressed the Enter 
key. 


Any values specified in the source procedure cannot be changed directly by the 
operator (or user). For example: 


PGM 
?SNDMSG TOMSGQ(WSO1 WS@2) 


ENDPGM 


When the procedure is called and the prompt for the Send Message (GNDMSG) 
command appears, the operator (or user) can enter values on the MSG, MSGTYPE, 
and RPYMSGQ parameters, but cannot alter the values on the TOMSGQ 
parameter. For example, the operator (or user) cannot add WS03 or delete WS02. 
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od Programs” on page for 


See LQ ocedure gra g 
ions apply to the use of the 


an exception to this restriction. The following restrict 
prompter within a CL procedure at processing time: 


* When the prompter is called from a CL procedure or program, you cannot enter 
a variable name or an expression for a parameter value on the prompt. 


* Prompting cannot be requested on a command embedded on an IF, ELSE, or 
MONMSG command: 


Correct Incorrect 

IF (&A=5) THEN(DO) IF (&A=5) THEN(?SNDMSG) 
?SNDMSG 
ENDDO 

* Prompting cannot be used for the following commands: 

CALLPRC ELSE PGM 

CALL ENDDO RCVF 

CHGVAR ENDPGM RETURN 

COPYRIGHT ENDRCV SNDF 

DCL IF SNDRCVF 

DCLF GOTO WAIT 

DO MONMSG 


* Prompting cannot be used in batch jobs. 


When you enter a prompting request (?) on a command in a CL source file 
member, you may receive a diagnostic message on the command and still have a 
successful compilation. In this case, you must examine the messages carefully to 
see that the errors can be corrected by values entered through the prompt display 
when the procedure or program runs. 


You can prompt for all commands you are authorized to in any mode while in an 
interactive environment except for the previously listed commands, which cannot 
be prompted for during processing of a CL procedure or program. This allows you 
to prompt for any command while at a work station and reduces the need to refer 
to the manuals that describe the various commands and their parameters. 


If you press F3 or F12 to cancel the prompted command while running that 
command, an escape message (CPF6801) is sent to the CL procedure or program. 
You can monitor for this message using the MONMSG command in the CL 
procedure or program. 


When you prompt for a command, your procedure or program does not receive 
the command string you entered. To achieve this, prompt using QCMDCHK, then 
run the command using QCMDEXC. You can also use QCAPCMD to prompt and 
run the command. 


Selective Prompting for CL Commands 


You can request to prompt for selected parameters within a command. This is 
especially helpful when you are using some of the longer commands and do not 
want to be prompted for certain parameters. 


Selective prompting can be used during interactive prompting or entered as source 
(in SEU) for use within a CL procedure or program. You can enter the source for 
selective prompting with SEU but you cannot use selective prompting while 
entering commands in SEU. 


You can use selective prompting to: 
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* Select the parameters for which prompting is needed. 
* Determine which parameters are protected. 
* Omit parameters from the prompt. 


The following restrictions apply to selective prompting: 
* The command name or label must be preceded by a ? (question mark): 
— When one or more of the selective prompt options is ?- (question mark, 
minus). 
- To avoid getting a CPF6805 message (a message that indicates a diagnostic 
problem on the command although compilation is successful) 


* Parameters can be specified by position but they cannot be preceded by selective 
prompt characters. 


* A parameter must be in keyword form to be selectively prompted for. 


* Blanks cannot be entered between the selective prompt characters and the 
keyword. 


* Selective prompting is only applicable at a parameter level; that is, you cannot 
specify particular keyword values within a list of values. 


* ?- is not allowed in prompt override programs. 
* If a parameter is required, the ?? selective prompt must be used. 


You can tell that a parameter is required because the input slot is highlighted 
when the command is prompted. 


User-specified values are marked with a special symbol (>) in front of the values in 
both selective and regular prompting. If a user-specified value on the parameter 
prompt is not preceded by this symbol, the command default is passed to the 
command processing program. 


If PASSATR(*YES) is specified on the PARM, ELEM, or QUAL command definition 
statement, and the default value is changed using the CHGCMDDFT command, 
the default value is shown as a user-specified value (using the > symbol) and not a 
default value. If a default value of a changed PARM, ELEM, or QUAL command 
definition statement is changed back to its original default value, the > symbol is 
removed. 


You can press F5 while you are using selective prompting to again display those 
values initially shown on the display. 


If a CL variable is used to specify a value for a parameter which is to be displayed 
through selective prompting, you can change the value on the prompt, and the 
changed value is used when the command is run. The value of the variable in the 
procedure or program is not changed. If a CL procedure contains the following: 


OVRDBF ?*FILE(FILEA) ??TOFILE(&FILENAME) ??MBR(MBR1) 


the three parameters, FILE, TOFILE, and MBR is shown on the prompt display. 
The value specified for the FILE parameter cannot be changed by you, but the 
values for the TOFILE and MBR parameters can be changed. Assume that the CL 
variable & FILENAME has a value of FILE1, and you change it to FILE2. When the 
command is run, the value of FILE2 is used, but the value of &FILENAME is not 
changed in the procedure. The following tables list the various selective prompting 
characters and the resulting action. 
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Value Passed to 

CPP if Nothing | Marked with > 
You Enter Value Displayed | Protected Specified Symbol 
??KEYWORD() Default No Default No 
??KEYWORD (VALUE)| Value No Value Yes 
?* KEYWORD () Default Yes Default No 
?*KEYWORD (VALUE) | Value Yes Value Yes 
?<KEYWORD () Default No Default No 
?<KEYWORD (VALUE) Value No Default No 
?/KEYWORD () Default Yes Default No 
?/KEYWORD(VALUE)| Value Yes Default No 
?-KEYWORD () None N/A Default N/A 
?-KEYWORD (VALUE)| None N/A Value N/A 
?&KEYWORD () Default No Default No 
?&KEYWORD (VALUE) | Value No Default No 
?%KEYWORD () Default Yes Default No 
?%KEYWORD (VALUE) | Value Yes Default No 


Display Value When F5 


You Enter Pressed or Blanked Out Description 

??KEYWORD() Default Normal keyword prompt with 
command default. 

??KEYWORD (VALUE) Value Normal keyword prompt with 


program specified default. 


?*KEYWORD () Default Show protected prompt (as 
information) where command 
default is the only value used. 


?* KEYWORD (VALUE) Value Show protected prompt (as 
information) where program 
specified value is the only 
value used. For example, 
when a value should be 
shown as information but not 


changed. 

?<KEYWORD () Default Normal keyword prompt with 
command default. 

?<KEYWORD (VALUE) Value Normal keyword prompt with 
program specified default. 

?/KEYWORD() Default Reserved for IBM use. 

?/KEYWORD (VALUE) Value Reserved for IBM use. 

2 &KEYWORD () Default Normal keyword prompt with 
command default. 

2? &KEYWORD (VALUE) Value Normal keyword prompt with 


program specified default. 


2%KEYWORD () Default Show protected prompt (as 
information) where command 
default is the only value used. 
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Display Value When F5 


You Enter Pressed or Blanked Out Description 
?%KEYWORD (VALUE) Value Show protected prompt (as 


information) where program 
specified value is the only 
value used. For example, 
when a value should be 
shown as information but not 
changed. 


Selective prompting can be used with the QCMDEXC or QCMDCHK program. The 
format of the call is: 


CALL PGM(QCMDEXC or QCMDCHK) PARM(command command-length) 


Following is a brief description of the selective prompting characters: 


Selective Prompting Character Description 
2? The parameter is displayed and input-capable. 
2x The parameter is displayed but is not input-capable. 


Any user-specified value is passed to the command 
processing program. 


?< The parameter is displayed and is input-capable, but 
the command default is sent to the CPP unless the 
value displayed on the parameter is changed. 


2/ Reserved for IBM use. 


?- The parameter is not displayed. The specified value 
(or default) is passed to the CPP. Not allowed in 
prompt override programs. 


28 The parameter is not displayed until F9=All 
parameters is pressed. Once displayed, it is 
input-capable. The command default is sent to the 
CPP unless the value displayed on the parameter is 
changed. 


2% The parameter is not displayed until F9=All 
parameters is pressed. Once displayed, it is not 
input-capable. The command default is sent to the 
CPP. 


QCMDEXC with Prompting in CL Procedures and Programs 


The QCMDEXC program may be used to call the prompter. This use of 
QCMDEXC with prompting in CL procedures and programs allows you to alter all 
values on the command except the command name itself. This is more flexible 
than direct use of the prompter, where you can only enter values not specified in 
the source (see previous section). If the prompter is called directly with a 
command such as: 


?0VRDBF FILE(FILEX) 
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you can specify a value for any parameter except FILE. However, if the command 
is called during processing of a program using the QCMDEXC program, such as: 


CALL QCMDEXC PARM('?0VRDBF FILE(FILEX)' 19) 


you can specify a value for any parameter, including FILE. In this example, FILEX 
is the default. 


Prompting with modifiable specified values may also be accomplished using 
selective prompting as described earlier in this chapter. However, each keyword 
which is desired must be explicitly selected. The prompter is called directly with a 
command such as: 


OVRDBF ??FILE(FILEX) ??TOFILE(*N) ??MBR(#N) 


Using the Programmer Menu 


The programmer menu can be called directly by calling the QPGMMENU 
program, or by using the Start Programmer Menu (STRPGMMNU) command. You 
can use the command to specify in advance the defaults that you use with the 
programmer menu. In addition, the STRPGMMNU command also supports other 
options that can be used to tailor the use of the programmer menu. 


For a description of the STRPGMMNU command and its parameters, see the CL 
section of the Programming category in the iSeries Information Center. 


Uses of the Start Programmer Menu (STRPGMMNU) Command 
The Start Programmer Menu command can be used for the following: 
* Performing the same function as a call to QPGMMENU 
* Filling in the standard input fields 
Four of the command parameters allow you to fill in the standard input fields at 
the bottom of the menu. These parameters are the following: 
-— Source file 
— Source library 
— Object library 
— Job description 


The command may be used with one or more of the parameters that control the 
initial values of the menu. You could design this as part of an initial program for 
sign-on or for situations in which a user calls a specific user-written function. The 
following example shows such a program, with a separate function for each 
application area requiring different initial values. 


PGM 
CHGLIBL LIBL(PGMR1 QGPL QTEMP) 


LOOP: 
STRPGMMNU SRCLIB(PGMR1) OBJLIB(PGMR1) JOBD(PGMR1) 
MONMSG MSGID(CPF2320) EXEC(GOTO END) /* F3 or F12 to leave menu */ 
GOTO LOOP 

END: ENDPGM 


* Controlling programmer menu options 


The other parameters assist you in controlling the menu and its functions. For 
example, you can specify ALWUSRCHG(*NO) to prevent a user from changing 
the values that appear on the menu. This parameter should not be considered to 
be a security feature because a user who is using the menu can call the 
STRPGMMNU command and change the values in a separate call. (The user can 
also start functions by using F10 to call the command entry display.) If the menu 
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is displayed by the STRPGMMNU command, you can prevent the user (by 
authorization) from calling the QPGMMENU program directly, but you cannot 
prevent the user from requesting another call of the STRPGMMNU command. 


Adapting the menu create option 


The EXITPGM and DLTOPT parameters allow you to provide your own support 
for the menu create option (option 3). The system may call a user program when 
you request option 3. IBM provides online information that discusses the 
parameters and the parameter list that are passed to the user program. Refer to 
the CL section of the Programming category in the iSeries Information Center. 
The following describes some typical uses of the EXITPGM parameter. 


The EXITPGM Parameter 
The EXITPGM parameter can be used for the following purposes: 


* To change the defaults used on the create commands submitted by option 3. 


For example, if F4 (Prompt) is not used, the EXITPGM parameter could change 
one or more of the create commands to specify your own default requirements. 
If F4 is used, the EXITPGM parameter could submit the command as entered by 
the programmer (with no parameters changed). 

* To change parameters regardless of the programmer’s use of F4. 
This requires scanning the value of the &RQSDTA512 parameter (which is 
passed to the exit program) to see if it had already been used and substituting 
the required value. 

* To change other parameters on the SBMJOB command. 


For example, the user parameter of the SBMJOB command could be changed to 
specify the value of the job description instead of the value of *CURRENT. It is 
also possible to retrieve the values of one or more job attributes by using the 
RIVJOBA command, entering the attributes as specific values. 

* To enforce local programming conventions. 
For example, if you have a naming standard that requires all physical files to be 
named with 7 characters and end with a P, the exit program could reject any 
attempt to use the CRTPF command with a name that did not follow this 
standard. 


Command Analyzer Exit Points 


The exit program registration facility provides two exit points for the system. 

* The QIBM_QCA_CHG_ COMMAND exit point can register one and only one 
exit point for a specific command. The program specified for this exit point is 
called by the command analyzer before it passes control to the prompter. 

* You can register up to ten exit programs for each command for the 
QIBM_QCA_RTV_COMMAND exit point. The command analyzer calls these 
exit programs after running the validity checking program (VCP) and before 
running the command processing program (CPP) for the command. 


See the APIs section of the Programming category in the iSeries Information Center 
for a complete description of these exit points. 


Application Programming for DBCS Data 


Special considerations must be made when designing application programs to 
process double-byte data or converting alphanumeric application programs to 
double-byte programs. 
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Designing DBCS Application Programs 


Design your application programs for processing double-byte data in the same 
way you design application programs for processing alphanumeric data, with the 
following additional considerations: 


Identify double-byte data used in the database files, if any. 
Design display and printer formats that can be used with double-byte data. 


If needed, provide double-byte conversion as a means of entering data for 
interactive applications. Use the DDS keyword for double-byte conversion 
(IGCCNV) to specify DBCS conversion in display files. 


Write double-byte error messages to be displayed by the program. 


Specify extension character processing so that the system prints and displays all 
double-byte data. 


Determine which double-byte characters, if any, must be defined. [ADTS/400;] 


e describes how to define double-byte characters 
for DBCS-supported countries. 


Converting Alphanumeric Programs to Process DBCS Data 


If an alphanumeric application program uses externally-described display files, you 
can change that application program to a double-byte application program by 
changing only the files. To convert an application program, do the following: 


1. 


Create a duplicate copy of the source statements for the alphanumeric file you 
want to change. 


Change alphanumeric constants and literals to double-byte constants and 
literals. 


Change fields in the file to one of the following data types to enter DBCS data: 
* DBCS-open (O) data type 

* DBCS-only (J) data type 

* DBCS-either (E) data 


You do not have to change the length of the fields. 


Store the converted display file in a separate library. Give the file the same 
name as its alphanumeric version. 

To use the converted file in a job, change the library list, using the Change 
Library List (CHGLIBL) command, for the job in which the file is used. The 
library in which the double-byte display file is stored is then checked before the 
library in which the alphanumeric version of the file is stored. 


Using DBCS Data in a CL Program 


The following program shows the use of different keyboard shifts within a CL 
program. Note how the double-byte data is used only as text values in this 
program, the commands themselves are in alphanumeric characters. 


When run, this program shows you how the different keyboard shifts for DDS 
display files are used. 
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PGM 
DCLF IGCTEST 


START: CHGVAR &8OUTPUTA ‘ABCDEFGHIJ' 


CHGVAR &OUTPUTJ ‘ABCD! 
CHGVAR &BOTHJ "ABCD! 
CHGVAR &OUTPUTE  , EFGH' 


CHGVAR &OUTPUTO 
aBc DF 


LOOP: SNDRCVF 


IF &INO1 RETURN 


CHGVAR &OUTPUTA = &INPUTA 
CHGVAR &OUTPUTJ  &INPUTJ 
CHGVAR &OUTPUTE &INPUTE 
CHGVAR &BOTHE &INPUTE 
CHGVAR &OUTPUTO INPUTO 


GOTO LOOP 


ENDPGM 


RV3W197-0 


Sample CL Programs 


The following sample programs demonstrate the flexibility, simplicity, and 
versatility of CL programs. The following programs are described by their function 
and probable user. 


Note: Code generated by the ILE CL compiler in V4R3 and later releases is 
threadsafe. However, many commands are not threadsafe. Therefore, do not 
consider a CL procedure as threadsafe unless all the commands the CL 
procedure uses are threadsafe. You can use the Display Command 
(DSPCMD) command to determine if a command is threadsafe. For 
additional information on threads, please access the iSeries Information 
Center and open the topics under the Programming category of information. 


Initial Program for Setup (Programmer) 


PGM 

CHGLIBL LIBL(TESTLIB QGPL QTEMP) 
CHGJOB OUTQ(WSPRTR) 

TFRCTL QPGMMENU 

ENDPGM 


The test library is placed first on the library list, an output queue is selected for a 
convenient printer, and the programmer menu is displayed. 
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Moving an Object from a Test Library to a Production Library 


(Programmer) 


PGM PARM(&0BJ &OBJTYPE &OPER) 
DCL &O0BJ *CHAR LEN(10) 
DCL &OBJTYPE *CHAR LEN(7) 
DCL &OPER «CHAR LEN(1) /* R=Replace M=Move */ 
IF ((Q0PER *NE 'M') *AND (8O0PER *NE 'R')) THEN(DO) 
SNDPGMMSG MSG('Operation code must be "R" or "M" ') 
RETURN 
ENDDO 
IF ((&0BJTYPE *NE *PGM) *AND (&OBJTYPE *NE *FILE) *AND (&0BJTYPE + 
*NE *DTAARA)) THEN(DO) 
SNDPGMMSG MSG('Object' *BCAT &0BJ *BCAT ' must be *PGM, + 
*FILE, or *DTAARA') 
RETURN 
ENDDO 
CHKOBJ BLDLIB/&0BJ OBJTYPE(&0BJTYPE) 
MONMSG MSGID(CPF9801) EXEC(DO) 
SNDPGMMSG MSG('Object or object type does not exist + 
in BLDLIB') 
RETURN 
ENDDO 
IF (80PER *EQ 'M') THEN(DO) 
MOVOBJ BLDLIB/&0BJ OBJTYPE(&0BJTYPE) TOLIB(PRODLIB) 
MONMSG MSGID(CPF3208) EXEC(DO) 
SNDPGMMSG MSG('Object' *BCAT &0BJ *BCAT ' + 
already exists in PRODLIB') 
RETURN 
ENDDO 
CHKOBJ PRODLIB/&0BJ OBJTYPE(&0BJTYPE) 
MONMSG MSGID(CPF9801) EXEC(DO) 
SNDPGMMSG MSG('Object or object type does not + 
exist in PRODLIB') 
RETURN 
ENDDO 
ENDDO 
RETURN 
ENDPGM 


The object name, object type, and operation code are passed from another program 
or procedure. Checks are performed to see that the operation code and object type 
are correct, and that the object exists in the test library. The object is moved unless 
it already exists in the production library. The move is then confirmed. More 
commands can be added to grant additional authority to the object or to handle 
additional exceptions and additional object types. 


Saving Specific Objects in an Application (System Operator) 


Example 

PGM 

SAVOBJ OBJ(FILE1 FILE2) LIB(LIBA) OBUJTYPE(*FILE) DEV(TAPO1) + 
CLEAR(*YES) 

SAVOBJ OBJ(DTAARA1) LIB(LIBA) OBJTYPE(*DTAARA) DEV(TAPO1) 

SNDPGMMSG MSG('Save of daily backup of LIBA completed') + 
MSGTYPE (*COMP) 

ENDPGM 


This program ensures consistent command entry for regularly repeated procedures. 
Additional Save Object (GAVOBJ) commands can, of course, be added. However, 
this program relies on the operator selecting the correct diskette or tape for each 


periodic backup of each application. This can be controlled by assigning unique 
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names to each diskette or tape set for each save operation. If you want to save 
your payroll files separately each week for four weeks, for instance, you might 
name each diskette or tape differently and write the program to compare the name 
of the diskette or tape against the correct name for that week. 


Recovery from Abnormal End (System Operator) 


PGM 
DCL &SWITCH *CHAR LEN(1) 
RTVSYSVAL SYSVAL(QABNORMSW) RTNVAR(&SWITCH) 
IF (&SWITCH *EQ '1') THEN(DO) /*CALL RECOVERY PROGRAMSx/ 
SNDPGMMSG MSG('Recovery programs in process. + 
Do not start subsystems until notified') + 
MSGTYPE(*INFO) TOMSGQ(QSYSOPR) 
CALL PGMA 
CALL PGMB 
SNDPGMMSG MSG('Recovery programs complete. + 
Startup subsystems') + 
MSGTYPE(*INFO) TOMSGQ(QSYSOPR) 
RETURN 
ENDDO 
ENDPGM 


Submitting a Job (System Operator) 


PGM /*DAILYAC*/ 

SBMJOB JOB(DAILYACCRC) JOBD(ACCRC2) + 
CMD(CALL ACCRC305 PARM(DAILY)) 

SNDPGMMSG MSG('Daily Accounts Receivable job DAILYACCRC + 
submitted to batch') MSGTYPE(*COMP) 

ENDPGM 


Instead of typing in all the parameters for submitting a job, the system operator 
simply calls DAILYAC. 


Timing Out While Waiting for Input from a Device Display 


PGM 
DCLF FILE(QGPL/MENU) 
START: SNDRCVF DEV(*FILE) RCDFMT(MENUFMT) WAIT(*NO) 
WATT 
MONMSG MSGID(CPFO889) EXEC(SIGNOFF) 
CHGVAR VAR(&IN99) VALUE('O') 
IF COND(&INO1) THEN(GOTO CMDLBL (START) ) 
OPTION: /* OPTION 1-ORDER ENTRY */ 
IF COND(&OPTION *EQ '1') THEN(DO) 
CALL PGM(ORDENT) 
GOTO CMDLBL(START) 
ENDDO 
OPTION2: /* OPTION 2-ORDER DISPLAY */ 
IF COND(&OPTION *EQ '2') THEN(DO) 
CALL PGM(ORDDSP) 
GOTO CMDLBL(START) 
ENDDO 
OPTION3: /* OPTION 3-ORDER CHANGE =/ 
IF COND(&OPTION *EQ '3') THEN(DO) 
CALL PGM(ORDCHG) 
GOTO CMDLBL(START) 
ENDDO 
OPTION4: /* OPTION 4-ORDER PRINT x/ 
IF COND(&OPTION *EQ '4') THEN(DO) 
CALL PGM(ORDPRT) 
GOTO CMDLBL(START) 
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ENDDO 
OPTIONS: /* OPTION 9-SIGNOFF */ 
IF COND(&OPTION *EQ '9') THEN(SIGNOFF) 
OPTIONERR: /* OPTION SELECTED NOT VALID */ 
CHGVAR VAR(&IN99) VALUE('1') 
GOTO CMDLBL (START) 
ENDPGM 


This program illustrates how to write a CL program using a display file that will 
wait for a specified amount of time for the user to enter an option. If he does not, 
the user is signed off. 


The display file was created with the following command: 


CRTDSPF FILE(MENU) SRCFILE(QGPL/QDDSSRC) SRCMBR(MENU) + 
DEV(*REQUESTER) WAITRCD(60) 


The display file will use the *REQUESTER device. When a WAIT command is 
issued, it waits for the number of seconds (60) specified on the WAITRCD 
keyword. The following is the DDS for the display file: 


SEQNBR *... ... Die ese oti sae sauce 8) suey diets De gin. wes Bo eee sek Bi Gievevers elev I ewe sx 8 
0100 A PRINT CAQ1(01) 

0200 A R MENUFMT BLINK 

0300 A TEXT('Order Entry Menu') 

0400 A 1 31'Order Entry Menu' 

0500 A 2 2'Select one of the following: ; 
0600 A 3. 4'1. Enter Order' 

0700 A 4 4'2. Display Order' 

0800 A 5 4'3. Change Order' 

0900 A 6 4'4. Print Order' 

1000 A 7 4'9. Sign Off' 

1100 A 23 2'Option:' 

1200 A OPTION 1 I 23 10 

1300 A 99 ERRMSG('Invalid option selected.') 


kee eee END OF SOURCE ** * & & 


The program performs a SNDRCVF WAIT(*NO) to display the menu and request 
an option from the user. Then it issues a WAIT command to accept an option from 
the user. If the user enters a 1 through 4, the appropriate program is called. If the 
user enters a 9, the SIGNOFF command is issued. If the user enters an option that 
is not valid, the menu is displayed with an ‘OPTION SELECTED NOT VALID’ 
message. The user can then enter another valid option. If the user does not 
respond within 60 seconds, the CPF0889 message is issued to the program and the 
MONMSG command issues the SIGNOFF command. 


A SNDF command using a record format containing the INVITE DDS keyword 
could be used instead of the SNDRCVF WAIT(*NO). The function would be the 
same. 


Retrieving Program Attributes 


You can use the Display Program (DSPPGM) command to display the attributes of 
a program. To retrieve some of the attributes (such as program type, source 
member, text, creation date) into CL variables, you can use the Display Object 
Description (DSPOBJD) command to build an output file. The system can then 
read a CL procedure or program that uses the Declare File (DCLF) and Receive File 
(RCVF) commands. To access other attributes of the DSPPGM command (such as 
USRPRF), you can use the Retrieve program information API (QCLRPGMI). 
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Loading and Running an Application from Tapes or Diskettes 


The Load and Run Media Program (LODRUN) command allows the user to load 
and run an application written by another user or a software vendor from tapes or 
diskettes supplied by the other user. 


When the LODRUN command is run: 


* The media is searched for the user-written program, which must be named 
QINSTAPP. If tape is used, the tape is rewound first. 

* If a QINSTAPP program already exists in the QTEMP library on the user’s 
system, it is deleted. 


* The QINSTAPP program is restored to the QTEMP library using the RSTOBJ 
command. 


* Control of the system is passed to the QINSTAPP program. The QINSTAPP 
program may be used, for example, to restore other applications to the user’s 
system and run those applications. 


Responsibilities of the Application Writer 


The user supplying the QINSTAPP program is responsible for writing and 
supporting it. The QINSTAPP program is not supplied by IBM*. The program can 
be designed to accomplish many different tasks. For example, the program could: 


* Restore and run other programs or applications 
* Restore a library 

* Delete another program or application 

* Create specific environments 


* Correct problems in existing applications 


Figure 3] shows an example of a QINSTAPP program. The program is saved to a 
tape or diskette by the program writer and loaded on the system using the 
LODRUN command. The LODRUN command passes control of the system to the 
program, which then performs the tasks written into the program. 


PGM PARM(&DEV) /* "Device" is only Parm allowed */ 
DCL VAR (&DEV) TYPE(*CHAR) LEN(10) 
DCL VAR(&MODEL) TYPE(*CHAR) LEN(4) 


/* Can check for appropriate model number, release level, and so on */ 
RTVSYSVAL SYSVAL(QMODEL) RTNVAR(&MODEL) 


IF (&MODEL *EQ 'xxxxx') THEN... 
/* Install a library for new application (programs, data): */ 
RSTLIB SAVLIB(NEWAPP) DEV(&DEV) ENDOPT(*LEAVE) + 
MBROPT (*ALL) 
/* Install a command to start new application: */ 
RSTOBJ OBJ(NEWAPP) SAVLIB(QGPL) DEV(&DEV) + 
MBROPT (+ALL) 
END: ENDPGM 


Figure 3. Example of an Application Using the LODRUN Command 
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Chapter 7. Defining Messages 


On the iSeries server, communication between procedures or programs, between 
jobs, between users, and between users and procedures or programs occurs 
through messages. A message can be predefined or immediate: 


* A predefined message is created and exists outside the program that uses it. 
Predefined messages are stored in message files and have a message number. An 
example of a system predefined message is: 

CPFO006 Errors occurred in command. 


* An immediate message is created by the sender at the time it is sent. An 
immediate message is not stored in a message file. An example of an immediate 
message received at a display station is: 


From ... :  QSYSOPR 06/12/94 10:50:54 
System going down at 11:00; please sign off 


Your system comes with an extensive set of predefined messages that allow 
communication between programs within the system and between the system and 
its users. Each licensed program you order has a message file that is stored in the 
same library as the licensed program it applies to. For example, system messages 
are stored in the file QCPFMSG in the library QSYS. 


The system uniquely identifies each predefined message in a message file by a 
7-character code and defines it by a message description. The message description 
contains information, such as message text and message help text, severity level, 
valid and default reply values, and various other attributes. See the Add Message 
Description (ADDMSGD) command description in online help, or in the CL section 
of the Programming category in the iSeries Information Center. 


All messages that are sent or received in the system are transmitted through a 
message queue. Messages that are issued in response to a direct request, such as a 
command, are automatically displayed on the display from which the request was 
made. For all other messages, the user, program or procedure must receive the 
message from the queue or display it. There are several IBM-supplied message 
queues in the system; these message queues are described later in this chapter (see 


The system also writes some of the messages that are issued to logs. A job log 
contains information related to requests entered for_a job, the history log contains 
job, subsystem, and device status information. See 
for more information on logging. 


You can create your own message files and message descriptions. By creating 
predefined messages, you can use the same message in several procedures or 
programs but define it only once. You can also change and translate predefined 
messages into languages other than English (based on the user viewing the 
messages) without affecting the procedures and programs that use them. If the 
messages were defined in the procedure or program, the module or program 
would have to be recompiled when you change the messages. 


In addition to creating your own messages and message files, the system message 
handling function allows you to: 
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Create and change message queues (Create Message Queue [CRTMSGQ], 
Change Message Queue [CHGMSGQ], and Work with Message Queues 
[WRKMSGQ] commands) 


Create and change message files (Create Message File [CRTMSGF], Change 
Message File [CHGMSGF] commands) 


Add message descriptions (Add Message Description [ADDMSGD] command) 


Change message descriptions (Change Message Description [CHGMSGD] 
command) 


Remove message descriptions (Remove Message Description [RMVMSGD] 
command) 


Send immediate messages (Send Message [SNDMSG], Send Break Message 
[SNDBRKMSG], Send Program Message [SNDPGMMSG], and Send User 
Message [SNDUSRMSG] commands) 


Display messages and message descriptions (Display Messages [DSPMSG], 

Display Message Description [DSPMSGD], Work with Messages [WRKMSG], 

and Work with Message Descriptions [WRKMSGD] commands) 

Use a CL procedure or program to: 

— Send a message to a work station user or the system operator (Send User 
Message [SNDUSRMSG] command) 

— Send a message to a message queue (Send Program Message [SNDPGMMSG] 
command) 

— Receive a message from a message queue (Receive Message [RCVMSG] 
command) 

— Send a reply for a message to a message queue (Send Reply [SNDRPY] 
command) 

— Retrieve a message from a message file (Retrieve Message [RTVMSG] 
command) 

— Remove a message from a message queue (Remove Message [RMVMSG] 
command) 

— Monitor for escape, notify, and status messages that are sent to a call message 
queue (Monitor Message [MONMSG] command) 

Use the system reply list to specify the replies for predefined inquiry messages 

sent by a job (Add Reply List Entry [ADDRPYLE], Change Reply List Entry 

[CHGRPYLE], Remove Reply List Entry [RMVRPYLE], and Work with Reply 

List Entry [WRKRPYLE] commands) 


When a message is sent, it is defined as one of the following types: 


Informational (*INFO). A message that conveys information about the condition 
of a function. 

Inquiry (*INQ). A message that conveys information but also asks for a reply. 
Notify (“NOTIFY). A message that describes a condition for which a procedure 
or program requires corrective action or a reply from its calling procedure or 
program. A procedure or program can monitor for the arrival of notify messages 
from the programs or procedures it calls. 

Reply (*RPY). A message that is a response to a received inquiry or notify 
message. 

Sender’s copy (*COPY). A copy of an inquiry or notify message that is kept by 
the sender. 


Request (*RQS). A message that requests a function from the receiving procedure 
or program. (For example, a CL command is a request message.) 
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* Completion (*COMP). A message that conveys completion status of work. 

* Diagnostic (*DIAG). A message about errors in the processing of a system 
function, in an application program, or in input data. 

* Status (*STATUS). A message that describes the status of the work done by a 
procedure or program. A procedure or program can monitor for the arrival of 
status messages from the program or procedure it calls. Status messages sent to 
the external message queue (*EXT) are shown at the display station and can be 
used to inform the display station user of an operation in progress. 

* Escape (*ESCAPE). A message that describes a condition for which a procedure 
or program must end abnormally. A procedure or program can monitor for the 
arrival of escape messages from the program or procedure it calls or from the 
machine. Control does not return to the sending program after an escape 
message is sent. 


This chapter describes: 

* How to create your own message files 

* How to add message descriptions to a message file 
* Types of message queues 

* How to create message queues 


Creating a Message File 


To create your own predefined messages, you must first create the message file 
into which the messages are to be placed. Use the Create Message File (CRTMSGF) 
command to create the message file. You then use the Add Message Description 
(ADDMSGD) command to describe your messages and place them in the message 
file. 


On the CRTMSGF command, you can specify the maximum size in K bytes on the 
SIZE parameter. The following formula can be used to determine the maximum: 


S + (I x N) 


where: 
S Is the initial amount of storage 
I Is the amount of storage to add each time 


N Is the number of times to add storage 
The defaults for S, I, and N are 10, 2, and *NOMAX, respectively. 


For example, you specify S as 5, I as 1, and N as 2. When the file reaches the initial 
storage amount of 5K, the system automatically adds another 1K to the initial 
storage. The amount added (1K) can be added to the storage two times to make 
the total maximum of 7K. If you specify *NOMAX as N, the maximum size of the 
message file is 16M. 


When you specify a maximum size for a message file and the message file 
becomes full, you cannot change the size of the message file. You then need to 
create another message file and re-create the messages in the new file. The Merge 
Message File (MRGMSGF) command can be used to copy message descriptions 
from one message file to another. Since you will want to avoid this step, it is 
important to calculate the size needed for your message file when you create it, or 
specify *NOMAX. 
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Message Files in Independent ASPs 


Message files can be created in an independent auxiliary storage pool (ASP), but it 
is not recommended because the independent ASP can be taken offline. This would 
prevent messages in job logs and message queues from being displayed correctly if 
the independent ASP is offline. 


Determining the Size of a Message File 


You can determine the size of a message by using the following formula. (The 
ADDMSGD command parameters are given in parentheses.) 


* Message index equals 42 bytes base plus the length of the message. 
* Message text (MSG) equals 16 bytes base plus the length of the message. 


* Message online help information (SECLVL), if any, equals 16 bytes base plus the 
length of the message help. 


* Formats (FMT), if any, equal 14 bytes plus (3 x number of FMTS). 
* Type and length (TYPE and LEN) equal 48 bytes. 

* Special value (SPCVAL) equals 2 plus (64 x number of SPCVALs). 
* Values (VALUES) equal 32 x (number of VALUES). 

* Range (RANGE) equals 64 bytes. 

* Relation (REL) equals the length of the relation. 

* Default (DFT) equals the length of the default reply. 


* Default program, log problem, and dump list (DFTPBM, LOGPRB, DMPLST) 
equal 35 plus (2 x number in DMPLST). 


* ALROPT equals 12 bytes. 


The smallest possible entry in a message file is 59 bytes and the largest possible 
entry is 5764 bytes. The following table describes the largest possible entry: 


Message index 42 bytes 
Message text 148 bytes 
Message help text 3016 bytes 
99 formats 311 bytes 
Type and length 48 bytes 
20 special values 1282 bytes 
20 values 640 bytes 
Default reply value 32 bytes 
Default program and dump list 233 bytes 
Alert option 12 bytes 


In the following example, the CRTMSGF command creates the message file 
USRMSG: 


CRTMSGF MSGF(QGPL/USRMSG) + 
TEXT('Message file for user-created messages') 


If you are creating a message file to be used with the DSPLY operation code in 
RPG for OS/400, the message file must be named QUSERMSG. 
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Adding Messages to a File 


You use the Add Message Description (ADDMSGD) command to describe your 
predefined messages and to add them to the message file you created. On the 
ADDMSGD command, you specify the message identifier, the name of the message 
file into which the message is to be placed, and the message description. In the 
message description, you can specify: 


* Message text (required) with optional substitution variables 
* Message help text with optional substitution variables 
* Severity code 


* Description of the format of the message data to be used for the substitution 
variables 


* Validity checking values for a reply 

* Default value for a reply 

* Default message handling action for escape messages 
* Creation level 

* Alert options 

¢ Entry in the error log 

* Coded Character Set ID (CCSID) 


Each of the items that can be contained in the message description is described in 
more detail on the following pages. 


The following commands are also available for use with message descriptions: 


Change Message Description (CHGMSGD) 
Changes a message description. 


Display Message Description (DSPMSGD) 
Displays a message description. (A range of message identifiers can be 
specified in this command.) 


Remove Message Description (RMVMSGD) 
Removes a message description from a message file. 


Retrieve Message (RTVMSG) 
Retrieves a message from a message file. 


Merge Message File (MRGMSGF) 
Merges messages from one message file into another message file. 


Work with Message Descriptions (WRKMSGD) 
Displays a list of messages in a file and allows you to add, change, or 
delete message descriptions. 


Assigning a Message Identifier 
The message identifier you specify on the ADDMSGD command is used to refer to 
the message and is the name of the message description. The message identifier 
must be 7 characters: 


pppmmnn 


where ppp is the product or application code, mm is the numeric group code, and nn 
is the numeric subtype code. The number specified as mmnn can be used to further 
divide a set of product or application messages. Numeric group and subtype codes 
consist of decimal numbers 0 through 9 and the characters A through F. 
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For example: 
CPF1234 


is message 1234 of CPF. 


When you create your own messages, using the letter U as the first character in the 
product code is a good way to distinguish your messages from system messages. 
For example: 


USR3567 


The first character of the code must be alphabetic, the second and third characters 
can be alphanumeric; the group code and the subtype code must consist of decimal 
numbers 0 through 9 and the characters A through F. Note that although this range 
can be called a set of hexadecimal numbers, any sorting of the message numerics 
treats A through F as characters. 


For example, when displaying a range of message descriptions, CPFA000 precedes 
CPF1000. 


You should use care in using a numeric subtype code of 00 in the message 
identifier. If you use a numeric subtype code of 00 for a message that can be sent 
as an escape, notify, or status message and that can, therefore, be monitored, a 

subtype code of 00 in the Monitor Message (MONMSG) command causes all 


Defining Messages and Message Help 


You can define two levels of messages on the ADDMSGD command. The text of 
the message is required and should identify the condition that caused the message 
to be issued. Message help is optional and should explain the condition further or 
explain the corrective action to be taken. To get message help, the display station 
user must move the cursor to the message line and press the Help key when the 
message is displayed. Message help can be formatted for the display station using 
three format control characters. These characters may be used to make the message 
help (usually online help information) more readable for the user. 


Each of the three format control characters must be followed by a blank to separate 
them from the message text. 


&Nb (where b is a blank) 
Forces the text to a new line (column 2). If the text is longer than one line, 
the next lines are indented to column 4 until the end of the text or until 
another format control character is found. 


&Pb (where b is a blank) 
Forces the text to a new line, indented to column 6. If the text is longer 
than one line, the next lines start in column 4 until the end of the text or 
until another format control character is found. 


&Bb (where b is a blank) 
Forces the text to a new line, starting in column 4. If the text is longer than 
one line, the next lines are indented to column 6 until the end of the text 
or until another format control character is found. 
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Assigning a Severity Code 


The severity code you assign to a message on the ADDMSGD command indicates 
how important the message is. The higher the severity code the more serious the 
condition is. The following lists the severity codes you can use and their meanings. 
(These severity codes and their meanings are consistent with the severity codes 
assigned to IBM-predefined messages.) 


00: Information. For information purposes only; no error was detected and no reply 
is needed. The message could indicate that a function is in progress or that a 
function has completed successfully. 


10: Warning. A potential error condition exists. The procedure or program may 
have taken a default, such as supplying missing input. The results of the operation 
are assumed to be successful. 


20: Error. An error has been detected, but it is one for which automatic recovery 
procedures probably were applied; processing has continued. A default may have 
been taken to replace erroneous input. The results of the operation may not be 
valid. The function may have been only partially completed; for example, some 
items in a list processed correctly while others failed. 


30: Severe error. The error detected is too severe for automatic recovery, and no 
defaults are possible. If the error was in source data, the entire input record was 
skipped. If the error occurred during procedure or program processing, it leads to 
an abnormal end of the procedure or program (severity 40). The results of the 
operation are not valid. 


40: Abnormal end of procedure or function. The operation has ended, possibly because 
the procedure or program was unable to handle data that was not valid, or 
possibly because the user has canceled it. 


50: Abnormal end of job. The job was ended or was not started. A routing step may 
have ended abnormally or failed to start, a job-level function may not have been 
performed as required, or the job may have been canceled. 


60: System status. Issued only to the system operator. It gives either the status of or 
a warning about a device, a subsystem, or the system. 


70: Device integrity. Issued only to the system operator. It indicates that a device is 
malfunctioning or in some way is no longer operational. The user may be able to 
recover from the failure, or the assistance of a service representative may be 
required. 


80: System alert. A message with a severity code of 80 is issued for immediate 
messages. It also warns of a condition that, although not severe enough to stop the 


system now, could become more severe unless preventive measures are taken. 


90: System integrity. Issued only to the system operator. It describes a condition that 
renders either a subsystem or the system inoperative. 


99: Action. Some manual action is required, such as entering a reply, changing 
printer forms, or replacing diskettes. 


For a detailed discussion of the SEV parameter, see the CL section of the 
Programming category in the iSeries Information Center. 
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Defining Substitution Variables 
On the FMT parameter on the ADDMSGD command, you can specify substitution 
variables for either first- or second-level messages. For example: 
File &1 not found 


contains the substitution variable &1. When the message is displayed or retrieved, 
the variable &1 is replaced with the name of the file that could not be found. This 
name is supplied by the sender of the message. For example: 


File ORDHDRP not found 


Compare this to: 
File not found 


Substitution variables can make your message more specific and more meaningful. 


The substitution variable must begin with & (ampersand) and be followed by n, 
where n is any number from 1 through 99. For example, for the message: 


File &1 not found 


the substitution variable is defined as: 
FMT((*CHAR 10)) 


When you assign numbers to substitution variables, you must begin with the 
number 1 and use the numbers consecutively. For example, &1, &2, &3, and so on. 
However, you do not have to use all the substitution variables defined for a 
message description in the message that is sent. 


For example, the message: 
File &3 not available 


is valid even though &1 and &2 are not used in the messages. However, to do this, 
you must define &1, &2, and &3 on the FMT parameter of the ADDMSGD 
command. For the preceding message, the FMT parameter could be: 


FMT((*CHAR 10) (*CHAR 2) (*CHAR 10)) 


where the first value describes &1, the second &2, and the third &3. The 
description for &1 and &2 must be present if &3 is used. In addition, when this 
message is sent, the MSGDTA parameter on the Send Program Message 
(SNDPGMMSG) command should include all the data described on the FMT 
parameter. To send the preceding message, the MSGDTA parameter should be at 
least 22 characters long. 


For the preceding message, you could also specify the FMT parameter as: 
FMT((*CHAR 0) (*CHAR 0) (*CHAR 10)) 


Because &1 and &2 are not used in the message, they can be described with a 
length of 0. Then no message data needs to be sent. (The MSGDTA parameter on 
the SNDPGMMSG command needs to be only 10 characters long in this case.) 


An example of using &3 in the message and including &1 and &2 in the FMT 
parameter is when &1 and &2 are specified on the DMPLST parameter. (The 
DMPLST parameter specifies that the data is to be dumped when this message is 
sent as an escape message to a program that is not monitoring for it.) 
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The substitution variables do not have to be specified in the message in the same 
order in which they are defined in the FMT parameter. For example, three values 
can be defined in the FMT parameter as: 


FMT((*CHAR 10) (*CHAR 10) (*CHAR 7)) 


The substitution variables can be used in the message as follows: 
Object &1 of type &3 in library &2 is not available 


If this message is sent in a CL procedure or program, you can concatenate the 
values used for the message data such as: 


SNDPGMMSG ..... MSGDTA(&0BJ *CAT &LIB *CAT &OBUTYPE) 


You must specify the format of the message data field for the substitution variable 
by specifying data type and, optionally, length on the ADDMSGD command. The 
valid data types for message data fields are: 


* Quoted character string (*“QTDCHAR). A string of character data to be enclosed 
in apostrophes. Preceding and trailing blanks are not deleted. If length is not 
specified in the message description, the sender determines the length of the 
field. 


* Character string (*CHAR). A string of character data not to be enclosed in 
apostrophes. Trailing blanks are deleted. If length is not specified in the message 
description, the sender determines the length of the field. 


* Convertible character string (*CCHAR). A string of character data not to be 
enclosed in apostrophes. Trailing blanks are deleted. The length is always 
determined by the sender. If data of this type is sent to a message queue that 
has a CCSID tag other then 65535 or 65534, the data is converted from the 
CCSID of the message data to the CCSID of the message queue. Conversions can 
also occur on data of this type when the data is obtained from the message 
queue using a receive or display function. See the Globalization topic in the 
Programming category of the iSeries Information Center for more information 
on the use of message handlers with CCSIDs. 


* Hexadecimal (*HEX). A string to be preceded by the character X and enclosed in 
apostrophes; each byte of the string is to be converted into two hexadecimal 
characters (0 through 9 and A through F). If length is not specified in the 
message description, the sender determines the length of the field. 


* Binary (*BIN). A binary integer (either 2, 4, or 8 bytes long) formatted as a 
signed decimal integer. Unless provided a specified length, the system will 
assume that the binary integer is 2. 


* Unsigned binary (*UBIN). An unsigned binary integer (either 2, 4 or 8 bytes 
long) formatted as an unsigned decimal integer. Unless provided a specified 
length, the system will assume that the binary integer is 2. 


* Decimal (*DEC). A packed decimal number to be formatted as a signed decimal 
number with a decimal point. Length must be specified; decimal positions 
default to 0. 

* System pointer (*SYP). A 16-byte pointer to a system object. In a message or 
message help, the 10-character name of the object is formatted the same as the 
*CHAR type data. 

* Space pointer (*SPP). A 16-byte pointer to a program object. In a dump, the data 
in the object is formatted the same as the *HEX type data. *SPP cannot be used 
as substitution text in a message; it can only be used as part of the DMPLST 
parameter on the ADDMSGD command. 
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The following data types are valid only in IBM-supplied message descriptions and 
should not be used for other messages: 


* Time interval (*ITV). An 8-byte time interval that contains the time to the nearest 
whole second for various wait time out conditions. 


* Date and time stamp (*DTS). An 8-byte system date and time stamp for which 
the date is to be formatted as specified in the QDATFMT and QDATSEP system 
values and the time is to be formatted as hh:mmiss. 


Specifying Validity Checking for Replies 
On the ADDMSGD command, you can specify the type of reply that is valid for an 
inquiry or notify message. You can specify (parameters are given in parentheses): 
* Type of reply (TYPE) 
— Decimal (*DEC) 
— Character (*CHAR) 
— Alphabetic (*ALPHA) 
— Name (**NAME) 
* Maximum length of reply (LEN) 
— For decimal, 15 digits (9 decimal positions) 
— For character and alphabetic, 32 characters 
— For name, 10 characters 


Note: If you do not specify any validity checking (VALUES, RANGE, REL, 
SPCVAL, DFT), the maximum length of a reply is 132 characters for types 
*CHAR and *ALPHA. 


* Values that can be used for the reply 
— A list of values (VALUES) 
A list of special values (GSPCVAL) 
A range of values (RANGE) 
— Asimple relationship that the reply value must meet (REL) 


Note: The special values are values that can be accepted but that do not satisfy 
any other validity checking values. 


When a display station user enters a reply to a message, the keyboard is in lower 
shift which causes lowercase characters to be entered. If your program needs the 
reply to be in uppercase characters, you can do one of the following: 


* Use the SNDUSRMSG command which supports a translation table option 
which defaults to converting lowercase to uppercase. 


* Require the display station user to enter uppercase characters by specifying only 
uppercase characters for the VALUES parameter. 


* Specify the VALUES parameter as uppercase and use the SPCVAL parameter to 
convert the corresponding lowercase characters to uppercase. 


* Use TYPE(*NAME) if the characters to be entered are all letters (A-Z). The 
characters are converted to uppercase before being checked. 


Sending an Immediate Message and Handling a Reply 
In this example, the procedure does the following: 
* Sends an immediate inquiry message to QSYSOPR 
* Requests a reply of yes or no (Y or N) 
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* Ensures that a valid reply has been entered 
* Does a time-out if the operator does not reply within 120 seconds 


PGM 
DCL &MSGKEY *CHAR LEN(4) 
DCL &MSGRPY *CHAR LEN(1) 
SNDMSG: SNDPGMMSG MSG('.... Reply Y or N') TOMSGQ(QSYSOPR) + 


MSGTYPE(*INQ) KEYVAR(&MSGKEY) 
RCVMSG MSGTYPE(*RPY) MSGKEY(&MSGKEY) WAIT(120) + 


MSG (&MSGRPY) 
IF ((&MSGRPY *EQ 'Y') *OR (&MSGRPY *EQ 'y')) DO 
GOTO END 
ENDDO /* Reply of Y */ 
IF ((&MSGRPY *EQ 'N') *OR (&MSGRPY *EQ 'n')) DO 
GOTO END 
ENDDO /* Reply of N */ 
IF (&8MSGRPY «NE ' ') DO 
SNDPGMMSG MSG('Reply was not Y or N, try again') + 
TOMSGQ(QSYSOPR) 
GOTO SNDMSG 
ENDDO /* Reply not valid */ 


/* Timeout occurred */ 
SNDPGMMSG MSG('No reply from the previous message + 
was received in 120 seconds and a 'Y'' + 
value was assumed') TOMSGQ(QSYSOPR) 


END: ENDPGM 


The SNDUSRMSG command cannot be used instead in this procedure because it 
does not support a time-out option (GNDUSRMSG waits until it receives a reply or 
until the job is canceled). 


The SNDPGMMSG command sends the message and specifies the KEYVAR 
parameter. This returns a message reference key, which uniquely identifies this 
message so that the reply can be properly matched with the RCVMSG command. 
The KEYVAR value must be defined as a character field length of 4. 


The RCVMSG command specifies the message reference key value from the 
SNDPGMMSG command for the MSGKEY parameter to receive the specific 
message. The reply is passed back into the MSG parameter. The WAIT parameter 
specifies how long to wait for a reply before timing out. 


When the reply is received, the procedure logic checks for an upper or lower case 
value of the Y or N. Normally the value is entered by the operator as a lower case 
value. If the operator enters a non-blank value other than Y or N, the procedure 
sends a different message and then repeats the inquiry message. 


If the operator had entered a blank, no reply is sent to the procedure. If a blank is 
returned to the procedure, the time out occurred (the operator did not reply). The 
procedure sends a message to the system operator stating that a reply was not 
received and the default was assumed (the “Y’” value is shown as ’Y’ in the 
message queue). Because the assumed value of ’Y’ is not displayed as the reply, 
you cannot determine when looking at a message queue whether the message 
should be answered or has already timed out. The procedure does not remove a 
message from the message queue once it has been sent. The second message 
should minimize this concern and provides an audit trail for what has occurred. 
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If the time out has already occurred and the operator replies to the message, the 
reply is ignored. The operator receives no indication that the reply has been 
ignored. 


Sending Immediate Messages with Double-Byte Characters 
To send an immediate message with double-byte text, limit the text to 37 
double-byte characters plus the shift control characters. The limited size of the 
message ensures it is properly displayed. 


Defining Default Values for Replies 


The ADDMSGD command allows you to specify a default value for a reply to your 
message. A default reply must meet the same validity checking values as the other 
replies for the message or be specified as a special value in the message 
description. A default value is used when a user has indicated (using the 
CHGMSGQ command) that default replies should be issued for all inquiry 
messages sent to the user’s message queue. Default replies are also sent when the 
unanswered inquiry messages are deleted. For example, the work station user uses 
the DSPMSG command to display messages, and removes unanswered inquiry 
messages by pressing either F13 to delete all the messages or F11 to delete a 
particular message. 


Default replies are also used when the job attribute of INQMSGRPY is set to *DFT 
and may be used if set to *SYSRPYL option. You can use the system reply list to 
change the default reply. 


Default replies are also used on the Display Program Messages screen (which 
shows messages that are sent to *EXT). The sending of the default reply occurs 
during either of the two following conditions: 


* The Display Program Messages screen appears showing an unanswered inquiry 
message and the user presses (to continue) without keying-in any reply. 


* The user pressed the key to exit the Display Program Messages screen. 


Specifying Default Message Handling for Escape Messages 


For each message you create that can be sent as an escape message, you can set up 
a default message handling action to be used if the message, when sent, is not 
handled any other way. 


Default message handling actions can consist of: 


* Default program name. A program to be called that takes default action to 
handle a message. The following parameters are passed to the default program: 
— Call message queue name. This parameter is a structure that consists of many 
fields that identify where the system sent the message. IBM has provided 
online information on default handling exit programs and details on the fields 
in the parameter. Refer to the CL section of the Programming category of the 
iSeries Information Center. 
— Message reference key (4 characters). The message reference key of the escape 
message on the call message queue. 
* Dump list. A list of message data field numbers (the same numbers as the 
substitution variables) that indicate which objects are to be dumped. 
In addition, you can dump any of the following: 
— The data areas for the job 
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— An internal machine data structure of a job 

— Ajob 
Specifying a dump list for a job is equivalent to specifying the Display Job 
(DSPJOB) command with the parameters JOB(*) OUTPUT (*PRINT). 


If you do not specify default actions in message descriptions, you will get a dump 
of the job (as if DSPJOB JOB(*) OUTPUT(*PRINT) was specified). 


The default action specified in a message is taken only after the message 
percolation action is completed without the escape message being handled. See 
41} for more information on handling defaults. 


Example of a Default Program 
The following program is a sample default program that could be used when a 


diagnostic message is sent followed by an escape message. This program could be 
an OPM CL program or an ILE program that has this single CL procedure. 


PGM PARM(&MSGQ &MRK) 

DCL VAR(&MRK) TYPE(*CHAR) LEN(4) 

DCL VAR(&MSGQ) TYPE(*CHAR) LEN(6381) 

DCL VAR(&QNAME) TYPE(*CHAR) LEN(4096) 

DCL VAR(&MODNAME) TYPE(*CHAR) LEN(10) 

DCL VAR(&BPGMNAME) TYPE(*CHAR) LEN(10) 

DCL VAR(&BLANKMRK) TYPE(*CHAR) LEN(4) VALUE(' ') 
DCL VAR(&DIAGMRK) TYPE(*CHAR) LEN(4) VALUE(' ') 
DCL VAR(&SAVEMRK) TYPE(*CHAR) LEN(4) 

DCL VAR(&MSGID) TYPE(*CHAR) LEN(7) 

DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(100) 

DCL VAR(&MSGF) TYPE(*CHAR) LEN(10) 

DCL VAR(&MSGLIB) TYPE(*CHAR) LEN(10) 

DCL VAR(&0FFSET) TYPE(*DEC) 

DCL VAR(&LENGTH) TYPE(*DEC) 

/* Check for OPM program type */ 
IF (%SST(&MSGQ 277 1) *EQ 'O') THEN(DO) 


CHGVAR VAR(&QNAME) VALUE(%SST(&MSGQ 1 10)) 
CHGVAR VAR(&MODNAME) VALUE('*NONE') 
CHGVAR VAR(&BPGMNAME) VALUE('*NONE') 

ENDDO 
ELSE DO 
/* Not an OPM program; always use the long procedure name */ 

CHGVAR VAR(&OFFSET) VALUE(%BIN(&MSGQ 281 4)) 


CHGVAR VAR(&LENGTH) VALUE(%BIN(&MSGQ 285 4)) 

CHGVAR VAR(&QNAME) VALUE(%SST(&MSGQ &OFFSET &LENGTH) ) 
CHGVAR VAR(&MODNAME) VALUE(%SST(&MSGQ 11 10)) 

CHGVAR VAR(&BPGMNAME) VALUE(%SST(&MSGQ 1 10)) 

ENDDO 


GETNEXTMSG: CHGVAR VAR(&SAVEMRK) VALUE (&DIAGMRK) 
RCVMSG PGMQ(*SAME (&QNAME &MODNAME &BPGMNAME)) + 
MSGTYPE(*DIAG) RMV(*NO) KEYVAR(&DIAGMRK) 
IF (&DIAGMRK *NE &BLANKMRK) THEN(GOTO GETNEXTMSG) 
ELSE IF (&SAVEMRK *NE ' ') THEN(DO) 
/* If no diag message is sent, no message is sent to the previous program */ 
RCVMSG PGMQ(*SAME (&QNAME &MODNAME &BPGMNAME)) + 
MSGKEY (&SAVEMRK) RMV(*NO) MSGDTA(&MSGDTA) + 
MSGID(&MSGID) MSGF(&MSGF) MSGFLIB(&MSGLIB) 
SNDPGMMSG MSGID(&MSGID) MSGF(&MSGLIB/&MSGF) + 
MSGDTA(&MSGDTA) TOPGMQ(*PRV (&QNAME + 
&MODNAME &BPGMNAME) ) 
MSGTYPE (*ESCAPE) 


ENDDO 
ENDPGM 


The program receives all the diagnostic messages in FIFO order. Then it sends the 


last diagnostic message as an escape message to allow the previous program to 
monitor for it. 
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Specifying the Alert Option 

On the ADDMSGD command, you can specify an alert option to allow an alert to 
be created for a message. A message, for which an alert can be created, can cause 
an SNA alert to be created and sent to a problem management focal point. The 
alert created for a message can be defined using the Add Alert Description 
(ADDALRD) command. For more information about the OS/400 alerts support, see 


the DENX Suppor book 


Example of Describing a Message 


In the following example, the ADDMSGD command creates a message to be used 
in applications such as order entry. The message is issued when a customer 
number entered on the display is not found. The message is: 


Customer number &1 not found 


The ADDMSGD command for this message is: 


ADDMSGD MSGID(USR4310) + 
MSGF(QGPL/USRMSG) + 
MSG('Customer number &1 not found') + 
SECLVL('Change customer number') + 
SEV(40) + 
FMT ((*CHAR 8)) 


The message is added to the USRMSG file in the library QGPL. 


You can use the DSPMSGD or WRKMSGD command to print or display message 
descriptions. 


The SECLVL parameter provides very simple text. To make this appear on the 
Additional Message Information display, you specify SECLVL('message text'). The 
text you specify on this parameter appears on the Additional Message Information 
display when you press the Help key after placing the cursor on this message. 


Defining Double-Byte Messages 


To define a message with double-byte text, write a CL procedure or program using 
the ADDMSGD command. The defined message is put into a message file and 
then sent normally. When writing the program, do the following: 

1. Make sure the source file containing the program is a double-byte file. Specify 
IGCDTA(*YES) on the Create Source Physical File (CRTSRCPF) command. 

2. Use the source entry utility (SEU) to enter the program. CL commands using 
double-byte characters can only be entered through SEU. For this reason, 
double-byte messages must be created in a CL program. 

3. Limit the length of the message to 37 double-byte characters, so the complete 
message can be displayed or printed. 

When using the MONMSG command, also limit the Comparison Data 
(CMPDATA) parameter to 6 double-byte characters. 

4. If the double-byte message file replaces an alphanumeric message file (such as 
files of translated messages to be sent only to double-byte display stations), 
enter a command similar to the following to override the alphanumeric 
message file: 

OVRMSGF MSGF(QCPFMSG) TOMSGF (DBCSLIB/QCPFMSG) 


Double-byte messages can be displayed only at double-byte display stations. 
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System Message File Searches 


The system uses the following two steps when searches are performed to retrieve a 
message from a message file: 


1. The system processes any overrides that are in effect for the message file name. 


for more information. 


2. If the message file name has not been overridden, the system searches for the 
message file based on the message file name and library specified when the 
message was used. 


for more information. 


Searching for a Message File 


When a message file has not been overridden, the message file name and library 
specified (at the time the message file was sent) are used to search for the message 
file from which the message description is retrieved. 


When a message file name is overridden but the message identifier is not 
contained in the overridden file, the message file name and library specified are 
also used to search for the message file. 


The system search depends on whether you specify the message file library as 
either *CURLIB or *LIBL. The following describes the search path for *CURLIB and 
*LIBL: 


* Specify as *CURLIB or explicitly specify the message file library 


The system searches for the message file named in the specified library or the 
job’s current library (*CURLIB). 


* Specify the message file library as *LIBL 


The system searches for the message file named in the job’s library list (*LIBL). 
The search stops after finding the first message file with the specified name. 


If the message file is found, but does not contain a description for the message 
identifier, the message attributes and text of message CPF2457 in QCPFMSG are 
used in place of the missing message description. 


If the message file was not found, the system attempts to retrieve the message 
from the message file that was used at the time the message was sent. 


Note: A message file may be found but cannot be accessed due to damage or an 
authorization problem. 


Overriding Message Files 


You can override message files used in a procedure or program. The creation 
(Override Message File command), deletion (Delete Override command), and 
display (Display Override command) of message file overrides is similar to other 
types of overrides. Here, however, only the name of the message file, not the 
attributes, is overridden, and the rules for applying the overrides are slightly 
different. 


To override a message file, use the Override Message File (OVRMSGF) command. 


The file overridden is specified in the MSGF parameter; the file overriding it is 
specified in the TOMSGF parameter. 
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For example, to override QCPFMSG with a user message file named USRMSGF, 
the following command would be used: 


OVRMSGF MSGF(QCPFMSG) TOMSGF (USRMSGF) 


When a predefined message is retrieved or displayed, the overriding file is 
searched for a message description. If the message description is not found in that 
file, the overridden file is searched. 


There are several basic reasons to override message files: 


To provide changed default replies or dump lists. A message file can be created 
with message descriptions for messages with changed default replies or dump 
lists because those in the original message descriptions are not satisfactory. You 
can establish several operating environments, each with different default replies. 


To change severity levels of the messages. 

To provide a default program. 

To change the text of a message. If the text is blank, it appears to the user as if 
no message was sent. For example, you may not want the status message sent 
by the Copy File (CPYF) command to appear to the user. 

To provide translation of messages into national languages. Message files written 
in English can be overridden by message files written in other languages. (If all 
messages are changed, use the library list for the job to change the order of the 
message files instead of overriding the message files.) 


Another way you can select the message file from which messages are to be 
retrieved is by changing the order of the files in the library list for the job. 
However, if you use this approach, the search for the message stops on the first 
message file found that has the specified name. If the message is not in that file, 
the search stops. 


For example, assume that a message file named USRMSG is in library USRLIB1, 
and another message file named USRMSG is in library USRLIB2. To use the 


196 08/400 CL Programming V5R2 


message file in USRLIB1, USRLIB1 should precede USRLIB2 in the library list: 


Libraries 
QSYS 
Library List 
QSYS — 
QGPL — 
QTEMP — 
3 QGPL 
USRLIBI = |+— 
HK; | | —» 
USRLIB2 
QTEMP 
> 
USRLIBI 
>» USRMSG 
USRLIB2 
USRMSG 
RBAFN507-0 


The system searches the first message file found with the correct name. If that file 
does not contain the message, the search stops. However, if you use the OVRMSGF 
command, the system searches the overriding file, and if the message is not there, 
it searches the overridden file. 


Example of Overriding a Message File 
Assume that you want to change an IBM-supplied message for use in a job. For 
example, suppose you want to change message CPC2191, which says: 


Object XXX in YYY type *ZZZ deleted 


to say: 
Object XXX in YYY deleted 


Specifics on how to describe the FMT parameter are provided by displaying the 
detailed description of CPC2191. 


First, you create a message file: 
CRTIMSGF MSGF(USRMSG/OVRCPF) 
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Then you use the message CPC2191 as a basis for your message and add it to the 
message file: 


ADDMSGD MSGID(CPC2191) MSGF(USRMSG/OVRCPF) + 
MSG('Object &1 in &2 deleted') + 
SEV(QO0) FMT((*CHAR 10) (*CHAR 10)) 


You then use the OVRMSGF command to override the message file when you run 
the job: 
OVRMSGF MSGF(QCPFMSG) TOMSGF (USRMSG/OVRCPF) 


Libraries 
Library List QSYS 
QSYS >| QCPFMSG 
QGPL 
QTEMP 
USERLIB 
USRMSG QGPL 
QTEMP 
USERLI 
The system searches 
the overriding 
message file (USRMSG) 
for the message. If 
the message is not in USRMSG 
the overriding file, y) ovRCPF 
the system then 
searches the overidden 
file (QCPFMSG) . 
RBAFN537-0 


If you want to change this message for use in all your jobs, you can use the 
Change Message Description (CHGMSGD) command to change the message. Then 
you do not have to override the system message file. 


If you use the CHGMSGD command to change an IBM-supplied message, the 
message will need to be changed again when a new release of the system is 
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installed. To change the message again, you can place any changes in an input 
stream or a program that can be run at any time. 


You can also override overriding files. For example, you can specify the following 
OVRMSGF commands during a job. 


OVRMSGF MSGF(MSGFILE1) TOMSGF(MSGFILE2) 
OVRMSGF MSGF(MSGFILE2) TOMSGF(MSGFILE3) 


First, file MSGFILE1 was overridden with MSGFILE2. Second, MSGFILE2 was 
overridden with MSGFILE3. When a message is sent, the files are searched in this 


order: 

1. MSGFILE3 
2. MSGFILE2 
3. MSGFILE1 


You can prevent message files from being overridden. To do so, you must specify 
the SECURE parameter on the OVRMSGF command. 


Types of Message Queues 


All messages on the system are sent to a message queue. The system user or 
program associated with the message queue receives the message from the queue. 
Similarly, a reply to a message is sent back to the message queue of the user or 
program requesting the reply. 


The following diagrams show the message queues supplied by IBM. A message 
queue is supplied for each display station (where DSP0O1 and DSP02 are display 
station names) and each user profile (where BOB and RAY are user profile names): 


DSPO1 DSP02 a aca |) SP XX 
BOB RAY pais JOE 
RBAFN560-0 


Job message queues are supplied for each job running on the system. Each job is 
given an external message queue (*EXT) and each call of an OPM program or ILE 
procedure within the job has its own call message queue. 


JOB1 JOB2 JOBx 

*EXT *EXT *EXT External message queue 
PROGI PROC_A| *** | PROGX Call message queues 
PROC_1 PROGB PROC_Y 

PROC_2 PROGC PROGZ 


RBAFN561-0 
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Message queues are also supplied for the system history log (QHST) and the 
system operator (QSYSOPR): 


QHST QSYSOPR 


RBAFN562-0 


These message queues are used as follows: 


* Work station message queues are used for sending and receiving messages 
between work station users and between work station users and the system 
operator. The name of the queue is the same as the name of the work station. 
The queue is created by the system when the work station is described to the 
system. 


* User profile message queues can be used for communication between users. 
User profile message queues are automatically created in library QUSRSYS when 
the user profile is created. 


* Job message queues are used for receiving requests to be processed (such as 
commands) and for sending messages that result from processing the requests; 
the messages are sent to the requester of the job. Job message queues exist for 
each job and only exist for the life of the job. Job message queues consist of an 
external message queue (*EXT) and a set of call stack entry message queues. See 

03] for more information. 


* System operator message queue (QSYSOPR) is used for receiving and replying 
to messages from the system, display station users, and application programs. 


* The history log message queue is used for sending information to the history log 
(QHST) from any job in the system. 


In addition to these message queues, you can create your own user message 
queues for sending messages to system users and between application programs. 


Creating or Changing a Message Queue 


To create your own user message queues, you use the Create Message Queue 
(CRTMSGQ) command. In addition, you also use the Change Message Queue 
(CHGMSGQ) command to change the following attributes of your message queue. 


The attributes of a message queue are: 


* Whether changes to the message queue must be written immediately to the disk. 
Writing the changes immediately to the disk ensures that no messages are lost in 
cases like a system failure. Note that this will cause a decrease in system 
performance. 


* The method of delivery for messages arriving at a message queue. When a 
message queue is created, the method of delivery is defined as hold delivery. 
When a display station is signed on, the user’s message queue is set to the mode 
specified in the user profile. The types of delivery you can specify on the 
CHGMSGO command are: 


— Break delivery. A job is interrupted and a program is called to deliver the 
message. If a user program is not specified on the CHGMSGQ command that 
requests break delivery, or if *SAME is specified, the Display Message 
(DSPMSG) command automatically displays the message. Break messages for 
a job can be controlled with the BRKMSG parameter on the CHGJOB 
command. 
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— Notify delivery. Adisplay station user is notified by means of the Attention 
light or audible alarm (or by both) that a message is on the queue. The 
display station user can view the message by using the DSPMSG command. 


— Hold delivery. The message queue holds the messages until the display 
station user requests them with the DSPMSG command. 


— Default delivery. All messages are ignored, and any messages requiring a 
reply are sent the default reply for the message. 


* How to handle messages for break delivery. 


— Automatically run the DSPMSG command. For an interactive job, the 
messages are displayed at the display station if the severity code is high 
enough. For a batch job, the messages are listed to a spooled printer file if the 
severity code is high enough. 


— Call a break-handling program to handle the messages. You must use the 
CHGMSGQ command to specify the called program and to set the method of 
delivery to break mode. You can specify whether other jobs can reply to 
inquiry messages on the queue while it is in break mode with a 
break-handling program. 


* The severity code for filtering messages for break and notify delivery. Messages 
with severity equal to or greater than the minimum severity code specified are 
displayed. When the queue is created, the minimum severity code is set to 00. 
To change the minimum severity code, you must use the CHGMSGQ command. 


When the DSPMSG command is used to display messages on the message 
queue, the severity code filter (SEV) parameter can be used to filter the messages 
shown. This filter is used rather than the severity filter specified for the message 
queue at creation time. To use this filter, specify DSPMSG SEV(*MSGQ). You can 
use the DSPMSG command to determine the current severity code used for 
filtering break and notify messages. The code is displayed on the heading line of 
the message display. 


* Coded character set identifier (CCSID) associated with the message queue. 
Messages sent to this queue are converted to this CCSID. No conversions occur 
if the message queue CCSID is 65534 or 65535. If the message queue CCSID is 
65534, each message contains its own CCSID which is established by the sender. 


* Allow alerts for standard message queues. Allow alerts specifies if the queue 
being created allows alerts to be generated from alert messages that are sent to 
it. 


* Action to take when the message queue becomes full. You cannot change this 
attribute for message queue QHST; QHST sends CPF2460 when it is full. IBM 
ships QSYSOPR with this attribute that is originally set to wrap. 


— Send CPF2460 (Message queue cannot be extended) to the program or user 
that sends a message to the full queue. 


— Wrap the queue. Wrapping will remove messages on the queue to make space 
for a new message that is sent to the queue. 


Note: When a work station device description is created, the system establishes a 
message queue for the device to receive all action messages for the device. 
For work station printers, tape drives, and APPC devices, the MSGQ 
parameter can be used to specify a message queue when creating a device 
description. If no message queue is specified for these devices, the default, 
QSYSOPR, is used as the message queue. All other devices are assigned to 
the QSYSOPR message queue when they are created. 
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The message queue defined in your user profile is known as a user message 
queue. When you sign on the system using your profile, the user message queue is 
put into the delivery mode specified in your user profile. 


If your user message queue is in break or notify delivery mode while you are 
signed on a display station and then you sign on another display station, the user 
message queue will not change the delivery mode for the new sign on. User 
message queues (along with work station message queues and the QSYSOPR 
message queue) cannot have their delivery mode changed by a job when the 
message queue is in break or notify delivery mode for a different job. 


When you sign off the display station, or the job ends unexpectedly, the user 
message queue delivery mode is changed to hold mode, if the delivery mode of 
the user message queue is break or notify for this job. The user message queue 
delivery mode is also changed from break or notify mode to hold mode when you 
transfer to an alternative job. You can do this using the Transfer Secondary Job 
(TFRSECJOB) command or by pressing the System Request key and specifying 
option 1 on the System Request menu. 


After transferring to an alternative job, you sign on using your user profile. Your 
user message queue is put into the delivery mode specified in your user profile. 
This allows the user message queue to transfer to the alternative job. You are then 
able to transfer back and forth between these two jobs and have your user message 
queue follow you. 


However, if after transferring to an alternative job, you sign on using a user profile 
other than your own, the user message queue for the job from which you 
transferred is left in hold delivery mode. The user message queue for the user 
profile you signed on with is put in the delivery mode specified in that user 
profile. Because of this, your user message queue could be put into break or notify 
delivery mode by another user. If another user still has your user message queue 
in that delivery mode when you transfer back to the first job, your user message 
queue delivery mode cannot be changed back to the original delivery mode. 


The QSYSOPR message queue is the message queue for the system operator, unless 
it has been changed. The above situation can occur for a system operator as well. 


Message Queues in Independent ASPs 
See the article for details about the independent ASPs. 


It is recommended that message queues in independent ASPs should not be put 
into break mode. When a message queue is in break mode, the break program will 
not be called if the message queue is not in the thread’s library name space when a 
message is sent to the message queue. The libraries in the independent ASPs in the 
thread’s ASP group plus the libraries in the system ASP (ASP number 1) and basic 
user ASPs (ASP numbers 2-32) form the library name space for the thread. 


When sending an inquiry message to a message queue, the to message queue and 
the reply message queue both should be either in the system ASP or in the same 
independent ASP, otherwise the reply may not be sent to the reply message queue 
if either message queue was taken offline. 


Messages cannot be received in these situations: 


* from a message queue with a wait time, in an independent ASP that is varied 
off 
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* asa reply to an inquiry message sent to a message queue, in an independent 
ASP that is varied off 


A break handing program will not be able to change the library name space for the 
thread. 


Break-Handling Program 


A break-handling program is called whenever a message of equal or higher 
severity than the severity code filter arrives on a message queue that is in break 
delivery mode. To request a break-handling program, you must specify the name 
of the program and break delivery on the same CHGMSGQ command. The 
message handling program must receive the message with the Receive Message 
(RCVMSG) command so the message is marked as handled and the program is not 
called again. For more information on receiving messages and break handling 
programs, see | 


Note: This program cannot open a display file if the interrupted program is 
waiting for input data from the device display. 


You can use the system reply list to specify that the system issue the reply to 
specified predefined inquiry messages so that the display station user does not 
need to reply. See for more information. 


Example of Changing the Delivery Mode 

When the system is started, it puts the QSYSOPR message queue in break delivery 
when the controlling subsystem is started. However, if the system operator signs 
off, the message queue is put in hold delivery. When the system operator signs on 
again, QSYSOPR is placed in the mode specified in the QSYSOPR user profile. 


The following procedure in a CL initial program can be used to place the 
QSYSOPR message queue in break mode. Initial programs can use similar 
procedures to monitor message queues other than the one specified in a user’s own 
user profile. 
PGM /* Procedure to place a msg queue in break mode */ 
CHGMSGQ QSYSOPR DLVRY(*BREAK) SEV(50) 
MONMSG MSGID(CPFQ000) EXEC(SNDPGMMSG MSG('Unable to put QSYSOPR + 

message queue in *BREAK mode') TOPGMQ(*EXT) ) 
ENDPGM 


The procedure attempts to set the QSYSOPR message queue to break delivery with 
a severity level of 50. If this is unsuccessful, a message is sent to the external job 
message queue (EXT). When the program which contains this procedure ends, the 
initial menu is displayed. A severity level of 50 is used to decrease the number of 
break messages that interrupts the work station user. A common reason for failure 
is when another user has QSYSOPR in break mode already. 


Job Message Queues 


Job message queues are created for each job on the system to handle all the 
message requirements of the job. Job message queues for a single job consist of an 
external message queue (*EXT) and a set of call message queues. A call message 
queue is assigned to each ILE procedure and OPM program that is called within 
the job. In addition, a job log is created for each job. A job log is a logical queue 
which maintains all messages sent within a job in chronological order. You may 
send messages to the *EXT queue or to a call message queue. You do not send 
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messages to the job log. Rather a message sent to either *EXT or a call message 
queue is also logically added to the job log by the system. 


The external message queue (*EXT) is used to communicate with the external 
requester (such as a display station user) of the job. Messages (except status 
messages) sent to the external message queue of a job are also placed on the job 
464 for more information). 


If an informational, inquiry, or notify message is sent to the external message 
queue for an interactive job, the message is displayed on the Display Program 
Messages display. Additionally, the procedure waits for a reply to inquiry or notify 
messages from the display station user. Should the user not enter a reply and press 
the Enter key or F3 (Exit), the default message reply is returned to the sender of 
the message. If there is no default message reply, *N is sent. If you send an inquiry 
or notify message to the external message queue for a batch job, the system sends 
the default reply back to you. If there is no default message reply, *N is the reply. 
The system reply list may override the displaying of inquiries or the sending of 
default replies to inquiries to *EXT. 


If a status message is sent to the external message queue of an interactive job, the 
message is displayed on the message line of the display station. You can use status 
messages like this to inform the display station user of the progress of a 
long-running operation. For example, the system sends status messages when 
running the CPYF command if you copy a file with several members. 


Note: When your application completes the long-running operation, you must 
send another message to clear the message line at the display. You can use 
message CP19801, which is a blank message, for this purpose. For example: 


PGM 


SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Status 1') + 
TOPGMQ(*EXT) MSGTYPE(*STATUS) 


SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Status 2') + 
TOPGMQ(*EXT) MSGTYPE(*STATUS) 


SNDPGMMSG MSGID(CPI9801) MSGF(QCPFMSG) TOPGMQ(*EXT) + 
MSGTYPE(*STATUS) 


ENDPGM 


A call message queue is used to send messages between one program or procedure 
and another program or procedure. As long as a program or procedure is on the 
call stack (has not returned yet) its call message queue is active and messages can 
be sent to that program or procedure. Once the program or procedure returns, its 
call message queue no longer exists and messages can no longer be sent to it. 
Message types which can be sent to a call message queue include informational, 
request, completion, diagnostic, status, escape, and notify. 


The call message queue for an OPM program or ILE procedure is created when 
that program or procedure is called. The call message queue is exclusively 
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associated only with the call stack entry in which the program or procedure is 
running. A call message queue is identified indirectly by identifying the call stack 
entry. A call stack entry is identified by the name of the program or procedure that 
is running in that call stack entry. 


In the case of an OPM program, the associated call stack entry is identified by the 
(up to) 10 character program name. In the case of an ILE procedure, the associated 
call stack entry is identified by a three part name which consists of the (up to) 256 
character procedure name, the (up to) 10 character module name, and the (up to) 
10 character program name. The module name is the name of the module into 
which the procedure was compiled. The ILE program name is the name of the ILE 
program into which the module was bound. 


When identifying the call stack entry for an ILE procedure, it is sufficient to specify 
only the procedure name. If the procedure name by itself does not uniquely 
identify the call stack entry, the module name or the ILE program name can also 
be specified. If, at the time a message is sent, a program or procedure is on the call 
stack more than once, the name specified will identify the most recently called 
occurrence of that program or procedure. 


There are other methods to identify a call stack entry. These methods are discussed 
in detail in 


If an OPM or ILE program is compiled and then replaced while it is on the call 
stack, care must be taken when the program name is used to reference a call stack 
entry. For call stack entries that are earlier on the stack than the point at which the 
replace operation was done, the name reference will resolved to the replaced object 
which now exists in QRPLOBJ. These name references are valid as long as the 
replaced object continues to exist in the QRPLOBJ library. For entries on the stack 
that are more recent then the point at which the replace operation was done, the 
name reference is for the new version of the program. Because of the manner in 
which the version to use is determined, you should not place a program directly in 
the library QRPLOBJ. This library should be used exclusively for the replaced 
version of a program. A name reference to a program that you place directly into 
QRPLOBJ will fail. 


If a program object is removed or renamed while an occurrence of it is on the call 
stack, any name reference to the removed program or any name reference using 
the old name will fail. For ILE procedures, if you are using only the procedure and 
module name for a reference, renaming the program will not impact the name 
reference. If you are also using the ILE program name, the name reference will fail. 


A message queue for a call stack entry of a program or procedure is no longer 
available when the program or procedure ends. A message that was on the 
associated call message queue can only be referenced at that point by using the 
message reference key of the message. 


For example, assume that procedure A calls procedure B which calls procedure C. 
Procedure C sends a message to procedure B and ends. The message is available to 
procedure B. However, when procedure B ends, its call message queue is no longer 
available. As a result, you cannot access procedure B by using procedure A, even 
though the message appears in the job log. Procedure A cannot access messages 
that are sent to Procedure B unless Procedure A has the message reference key to 
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that message. 


Procedure A 


CALLPRC B 


Procedure B <— 


CALLPRC 


External message queue 


CRETURN Procedure A call message queue 


r> Procedure B call message queue 


Procedure C <— 


SNDPGMMSG 
RETURN 


Procedure C call message queue 


RBAFN5S08-0 

If procedure A needs to delete specific messages, you could do the following: 
* Have procedure C send specific messages to procedure A 

* Have procedure B resend the messages to procedure A 


The following figure shows the relationship of procedure calls, the job message 
queue, and the call stack entry queues. A connecting line (-----) indicates which 
message queue is associated with which call of a procedure. 


Procedure Stack Job Message Queue 
* OK ok 

Procedure A External message queue 
Procedure B Procedure A call message queue 
Procedure C oe, Bin be, . Procedure B call message queue 
Procedure D Procedure D call message queue 
Procedure B = Procedure B call message queue 
Procedure C a a a 


* * * * = Messages sent to Caller 

RBAFN532-0 
In the preceding figure, procedure B has two call stack entry queues, one for each 
call of the procedure. There are no message queues for procedure C because no 
messages were sent to procedure C. When procedure C sends a message to 
procedure B, the message goes to the call stack entry queue for the last call of 
procedure B. 


Note: When you are using the command entry display, you can display all the 
messages sent to the job message queue by pressing F10 (Include detailed 
messages). Once the messages are displayed, you can roll through them 
using one of the roll keys. 


You can also display the messages for a job by using the Display Job Log 
(DSPJOBLOG) command. 
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Chapter 8. Working with Messages 


This chapter discusses some of the ways that messages can be used to 
communicate between users and programs. Messages can be sent: 


* From one system user to another system user, even if the receiver of the 
messages is not currently using the system 


* From one OPM program or ILE procedure to another OPM program or ILE 
procedure 


* From a program or procedure to a system user, even if the receiver of the 
messages is not currently using the system 


Interactive system users can send only immediate messages and replies. 


OPM programs or ILE procedures can send immediate messages or predefined 
messages with user-defined data. In addition, programs or procedures can: 


* Receive messages 


* Retrieve a message description from a message file and place it into a program 
variable 


* Remove messages from a message queue 
* Monitor for messages 


Sending Messages to a System User 


Several commands can be used to send messages to system users: 
* Send Message (GNDMSG) 

* Send Break Message (GSNDBRKMSG) 

* Send Program Message (GNDPGMMSG) 

* Send User Message (GNDUSRMSG) 


SNDPGMMSG and SNDUSRMSG can only be used in batch or interactive OPM 
programs or ILE procedures. These commands cannot be entered on a command 
line. The SNDMSG command sends an informational or inquiry message to the 
system operator message queue (QSYSOPR), a display station message queue, or a 
user message queue. You can send an informational message to more than one 
message queue at a time. But you can send an inquiry message to only one 
message queue at a time. The message is delivered by the delivery type specified 
for the message queue. The message does not interrupt the user unless the 
message queue is in break mode. 


The following SNDMSG command is sent by a display station user to the system 
operator: 


SNDMSG MSG('Mount tape on device TAP1') TOUSR(*SYSOPR) 


The SNDBRKMSG command sends an immediate message from a work station, a 
program, or a job to one or more display stations to be delivered in the break 
mode regardless of what delivery mode the receiver’s message queue is set to. This 
command can be used to send a message only to display station message queues. 
You should use the SNDBRKMSG command when sending any message that 
requires the immediate attention of a display station user. You cannot ensure the 
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message will cause a break, because each job has control by using the BRKMSG 
parameter on the Change Job (CHGJOB) command. 


If you send an inquiry message, you can specify that the reply be sent to a 
message queue other than that of your display station. 


The following SNDBRKMSG command is sent by the system operator to all the 
display station message queues: 


SNDBRKMSG MSG('System going down in 15 minutes') 
TOMSGQ(*ALLWS) 


The disadvantage of sending this message is that it is sent to all users, not just 
those users who are active at the time the message is sent. 


Sending Messages from a CL Program 


Use the Send Program Message (GNDPGMMSG) command or the Send User 
Message (SNDUSRMSG) command to send a message from a CL procedure or 
program. 


Using the SNDPGMMSG command, you can send the following types of messages: 
° Informational 

* Inquiry 

* Completion 

* Diagnostic 

* Request 

° Escape 

* Status 

* Notify 


You can send messages from a CL procedure or program to the following types of 
queues: 


* External message queue of the requester of the job (see [Job Message Queues 
bn page 203) 


* System operator message queue 
* Work station message queue 
¢ User message queue 


To send a message from a procedure or program, you can specify the following on 

the SNDPGMMSG command: 

* Message identifier or an immediate message. The message identifier is the name 
of the message description for a predefined message. 

* Message file. The name of the message file containing the message description 
when a predefined message is sent. 

* Message data fields. If a predefined message is sent, these fields contain the 
values for the substitution variables in the message. The format of each field 
must be described in the message description. If an immediate message is sent, 
there are no message data fields. 


* Message queue or user to receive the message. 
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* Message type. The following indicates which types of messages can be sent to 
which types of queues (V = valid). 


Table 7. Valid Message Types for Message Queue Types 


Message Message Queue Type 

Type External Call QSYSOPR | Work User 
Station 

Informational | V Vv Vv Vv Vv 

Inquiry Vv Vv Vv Vv 

Completion | V Vv Vv Vv Vv 

Diagnostic Vv Vv Vv Vv Vv 

Request Vv Vv 

Escape V 

Status Vv Vv 

Notify Vv V 


* Coded character set identifier (CCSID). Specifies the coded character set 
identifier (CCSID) that the supplied message or message data is in. 

* Reply message queue. The name of the message queue that receives the reply to 
an inquiry message. By default, the reply is sent to the call message queue of the 
procedure or program that sent the inquiry message. 

* Key variable name. The name of the CL variable to contain the message 
reference key for a message. 


To send the message created in MExa 
you would use the following command: 
SNDPGMMSG MSGID(USR4310) MSGF(QGPL/USRMSG) + 


MSGDTA(&CUSNO) TOPGMQ(*EXT) + 
MSGTYPE(*INFO) 


The substitution variable for the message is the customer number. Because the 
customer number varies, you cannot specify the exact customer number in the 
message. Instead, declare a CL variable in the CL procedure or program for the 
customer number (&CUSNO). Then specify this variable as the message data field. 
When the message is sent, the current value of the variable is passed in the 
message: 


Customer number 35500 not found 


In addition, you do not always know which display station is using the procedure 
or program, so you cannot specify the exact display station message queue that the 
message is to be sent to (TOPGMQ parameter); therefore, you specify the external 
message queue *EXT. 


Messages 


Inquiry and Informational Messages 

Using the SNDUSRMSG command, you can send an inquiry message or an 
informational message to a display station user, the system operator, or a 
user-defined message queue. If you use the SNDUSRMSG command to send an 
inquiry message to the user, the procedure or program waits for a response from 
the user. The message can be either an immediate message or a predefined 
message. For an interactive job, the message is sent to the display station operator 
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by default. For a batch job, the message is sent to the system operator by default. 
To send a message from a procedure or program using the SNDUSRMSG 
command, you can specify the following on the SNDUSRMSG command: 


* Message identifier or an immediate message. The message identifier is the name 
of the message description for a predefined message. 


* Message file. The name of the message file containing the message description 
when a predefined message is sent. 


* Message data fields. If a predefined message is sent, these fields contain the 
value for the substitution variables in the message. The format of each field 
must be described in the message description. If an immediate message is sent, 
there are no message data fields. 


* Valid replies to an inquiry message. 

* Default reply value to an inquiry message. 

° Message type. 

* Message queue to which the message is to be sent. 


* Message reply. A CL variable, if any, that is to contain the reply received in 
response to an inquiry message. 


* Translation table. The translation table to be used, if any, to translate the reply 
value. This is normally used for translating lowercase to uppercase. 


* Coded character set identifier (CCSID). Specifies the coded character set 
identifier (CCSID) that the supplied message or message data is in. 


Completion and Diagnostic Messages 

Using the SNDPGMMSG command, you can send diagnostic and completion 
messages. You can send these message types to any message queue from your CL 
procedure or program. Diagnostic messages tell the calling program or procedure 
about errors detected by the CL procedure or program. Completion messages tell 
the results of work done by the CL procedure or program. 


Normally, an escape message is sent to the message queue of the calling program 
or procedure to tell the caller what the problem was or that diagnostic messages 
were also sent. For a completion message, an escape message is usually not sent 
because the requested function was performed. 


For an example of sending a completion message, assume that the system operator 
uses the system operator menu to call a CL program SAVPAY to save certain 
objects. The CL program contains only the following procedure which saves the 
objects and then issues the following completion message: 

PGM 

SAVOBJ OBJ(PAY1 PAY2) LIB(PAYROLL) CLEAR(*YES) 


SNDPGMMSG MSG('Payroll objects have been saved') MSGTYPE(*COMP) 
ENDPGM 


If the SAVOBJ command fails, the CL procedure function checks and the system 
operator has to display the detailed messages to locate the specific escape message 
explaining the reason for the failure as described later in this chapter. If the 
SAVOBJ command completes successfully, the completion message is sent to the 
call message queue associated with the program that displays the system operator 
menu. 


One of the advantages of completion messages is their consistency with 
IBM-supplied commands. Many IBM commands send completion messages 
indicating successful completion. Seeing the type of message sent to the job log can 
assist in problem analysis. 
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Status Messages 

You can send status messages from your CL procedure or program, using the 
SNDPGMMSG command, to a call message queue or to the external message 
queue (*EXT) for the job. When a status message is sent to a call message queue, 
the receiving program or procedure can monitor for the arrival of the status 
message and can handle the condition it describes. If the receiving program or 
procedure does not monitor for the message, control returns to the sender to 


resume progessing. See g ag a ora 


Escape and Notify Messages 

You can send escape messages from your CL procedure or program to the call 
message queue of the calling program or procedure with the SNDPGMMSG 
command. An escape message tells the caller that the procedure or program ended 
abnormally and why. The caller can monitor for the arrival of the escape message 
and handle the condition it describes. When the caller handles the condition, 
control does not return to the sender of an escape message. 


If the caller is another procedure within the same program, the program itself does 
not end. The procedure to which the escape message was sent is allowed to 
continue. If the escape message was sent to the caller of the program itself, then all 
active procedures within the program are ended immediately. As a result, the 
program cannot continue to run. If the caller does not monitor for an escape 
message, default system action is taken. 


You can send notify messages from a CL procedure or program to the message 
queue of the calling program or procedure or to the external message queue. A 
notify message tells the caller about a condition under which processing can 
continue. The calling program or procedure can monitor for the arrival of the 
notify message and handle the condition it describes. If the caller is an Integrated 
Language Environment procedure, it can perform the following functions: 


* It can handle the condition. 

* It can send a reply back to the caller. 

* It can allow the sending procedure to continue processing. 

If the caller is an OPM program and is not monitoring for the message, the sender 
receives a default reply. If the caller is an ILE procedure, then the message 


percolates to the control boundary. When finding no monitor, the system returns a 
default reply to the sender. The sender then resumes processing. See 


Immediate messages are not allowed as escape and notify messages. The system 
has defined the message CPF9898, which can be used for immediate escape and 
notify messages in application programs. For example: 


SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Error condition') + 
MSGTYPE (*ESCAPE) 


Examples of Sending Messages 


Example 1: The following CL procedure allows the display station user to submit a 
job by calling a CL program which contains this procedure instead of entering the 
Submit Job (SBMJOB) command. The procedure sends a completion message when 
the job has been submitted. 

PGM 

SBMJOB JOB(WKLYPAY) JOBD(USERA) RQSDTA('CALL WKLY PARM(PAY1)') 


SNDPGMMSG MSG('WKLYPAY job submitted') MSGTYPE(*COMP) 
ENDPGM 
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Example 2: The following CL procedure changes a message based on a parameter 
received from a program that is called from within the this procedure. The 
message is then sent by the CL procedure as a completion message. (The RCDCNT 
field is defined as characters in PGMA.) 
PGM 
DCL &RCDCNT TYPE(*CHAR) LEN(3) 
CALL PGMA PARM(&RCDCNT) 
SNDPGMMSG MSG('PGMA completed' *BCAT &RCDCNT *BCAT + 

"records processed') MSGTYPE(*COMP) 
ENDPGM 


Example 3: The following procedure sends a message requesting the system 
operator to load a special form. The Receive Message (RCVMSG) command waits 
for the reply. The system operator must enter at least 1 character as a reply to the 
inquiry message, but the procedure does not use the reply value. 
PGM 
DCL &MSGKEY TYPE(*CHAR) LEN(4) 
SNDPGMMSG MSG('Load special form') TOUSR(*SYSOPR) + 

KEYVAR(&MSGKEY) MSGTYPE(*INQ) 
RCVMSG MSGTYPE(*RPY) MSGKEY(&MSGKEY) WAIT(120) 


ENDPGM 


The WAIT parameter must be specified on the RCVMSG command so that the 
procedure waits for the reply. If the WAIT parameter is not specified, the 
procedure continues with the instruction following the RCVMSG command, 
without receiving the reply. The MSGKEY parameter is used in the RCVMSG 
command to allow the procedure to receive the reply to a specific message. The 
variable &MSGKEY in the SNDPGMMSG command is returned to the procedure 
for use in the RCVMSG command. 


Example 4: The following procedure sends a message to the system operator when 
it is run in batch mode or to the display station operator when it is run from a 
display station. The procedure accepts either an uppercase or lowercase Y or N. 
(The lowercase values are translated to uppercase by the translation table (TRNTBL 
parameter) to make program logic easier.) If the value entered is not one of these 
four, the operator is issued a message indicating the reply is not valid. 


PGM 
DCL &REPLY *CHAR LEN(1) 


SNDUSRMSG MSG('Update YTD Information Y or N') VALUES(Y N) + 
MSGRPY (&REPLY) 

IF (&REPLY *EQ Y) 

DO 


ENDDO 
ELSE 
DO 


ENDDO 


ENDPGM 
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Example 5: The following procedure uses the message CPF9898 to send an escape 


message. The text of the message is 'Procedure detected failure’. Immediate 
messages are not allowed as escape messages so message CPF9898 can be used 


with the message as message data. 


PGM 


SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) 
MSGDTA('Procedure detected failure') 


ENDPGM 


Example 6: The following procedure allows the system operator to send a message 
to several display stations. When the system operator calls the program, this 
procedure, contained within the called program, displays a prompt which the 
system operator can enter the type of message to be sent and the text for the 
message. The procedure concatenates the date, time, and text of the message. 


NORMAL: 


BREAK: 
ENDMSG: 


PGM 

DCLF WSMSGD 

DCL &MSG TYPE(*CHAR) LEN(150) 

DCL &HOUR TYPE(*CHAR) LEN(2) 

DCL &MINUTE TYPE(*CHAR) LEN(2) 

DCL &MONTH TYPE(*CHAR) LEN(2) 

DCL &DAY TYPE(*CHAR) LEN(2) 

DCL &WORKHR TYPE(*DEC) LEN(2 0) 

SNDRCVF RCDFMT (PROMPT) 

IF &IN91 RETURN /* Request was ended */ 

RTVSYSVAL QMONTH RTNVAR(&MONTH) 

RTVSYSVAL QDAY RTNVAR(&DAY) 

RTVSYSVAL QHOUR RTNVAR(&HOUR) 

IF (&HOUR *GT '12') DO 

CHGVAR &WORKHR &HOUR 

CHGVAR &WORKHR (&WORKHR - 12) 

CHGVAR &HOUR &WORKHR /* Change from military time «/ 

ENDDO 

RTVSYSVAL QMINUTE RTNVAR(&MINUTE) 

CHGVAR &MSG (‘From Sys Opr ' *CAT &MONTH *CAT '/' + 
*CAT &DAY + 
*BCAT &HOUR *CAT ':' *CAT &MINUTE + 
*BCAT &TEXT) 

IF (&TYPE *EQ 'B') GOTO BREAK 

SNDPGMMSG MSG(&MSG) TOMSGQ(WS1 WS2 WS3) 

GOTO ENDMSG 

SNDBRKMSG MSG(&MSG) TOMSGQ(WS1 WS2 WS3) 

SNDPGMMSG MSG('Message sent to display stations') + 
MSGTYPE (*COMP) 

ENDPGM 


The DDS for the display file, WSMSGD, used in this program follows: 
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A DSPSIZ(24 80) 
A R PROMPT TEXT('Prompt') 
A BLINK 
A CA03(91 'Return') 
A 1 2'Send Messages To Work Stations' 
DSPATR(HI) 
3 2'TYPE' 
+2VALUES('N' 'B') 
CHECK (ME) 
DSPATR(MDT) 
+3'(N = No breaks 
5 2'Text' 
+2LOWER 


TYPE 1. dj 


rrLS 


B = Break) ' 


TEXT 100 «1 


rrrr>y 


If the system operator enters the following on the prompt: 
B 


Please sign off by 3:30 today 


the following break message is sent: 
From Sys Opr 10/30 02:00 Please sign off by 3:30 today 


Call Stack Entry Identification on SNDPGMMSG 


If the CL procedure is to send a message to an OPM program or another ILE 
procedure, you must identify the call stack entry to which the message is sent. The 
message is sent to the call message queue of the identified call stack entry. 


The TOPGMQ parameter of the SNDPGMMSG command is used to identify the 
call stack entry to which a message is sent. Identification of a call stack entry 
consists of the following two parts: 


Specification of a base entry 

The specification TOPGMQ(*PRV *) identifies the base entry as being the one in 
which the procedure using the SNDPGMMSG command is running. The offset is 
specified as being one entry previous to that base. This specification identifies 
the caller of the procedure which is using the command. 

Offset specification of a base entry 

The offset specification (element 1 of TOPGMQ) identifies if you send the 
message to the base (*SAME) or if you send the message to the caller of the base 
(*PRV). 


To understand how to identify the base entry, element 2 of TOPGMQ, you also 
need to understand the call stack when an ILE program is running. Two programs 
are used to illustrate this. Program CLPGM1 is an OPM CL program and Program 
CLPGM2 is an ILE program. Since program CLPGM2 is ILE, it can consist of 
several procedures, such as: CLPROC1, CLPROC2, CLPROC3, and CLPROC4. At 
runtime the following calls take place: 


CLPGM1 is called first. 

CLPGM1 calls CLPGM2. 

CLPGM2 calls CLPROC1. 

CLPROC1 calls CLPROC2. 

CLPROC2 calls CLPROC3 or CLPROC4. 
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See Figure 4 on page 214 to understand the structure of the call stack when 
CLPROC2 calls CLPROC4. This figure illustrates the following considerations: 


* There is a one-to-one correspondence between a call stack entry and an OPM 
program; for each call of an OPM program, one new entry is added to the call 
stack. 


* An ILE program, as a unit, is not represented on the stack; instead, when an ILE 
program is called, one entry is added to the stack for each procedure that is 
called in the program. As a result, you send a message to an ILE procedure, not 
to an ILE program. 


Note: The first procedure to run when an ILE program is called is the Program 
Entry Procedure (PEP) for the program. In CL, this procedure (_CL_PEP) is 
generated by the system and calls the first procedure you provide. In this 
example, the entry for the PEP is between the entry for the OPM program 
CLPGM1 and the entry for the procedure CLPROC1. 


Following are different ways of specifying the base call stack entry. 
Procedure Using the Command as the Base 


If the TOPGMQ parameter specifies either TOPGMQ(*SAME *) or 

TOPGMQ(*PRV *), the entry for the procedure using the SNDPGMMSG command 
is used as the base. If TOPGMQ(*SAME *) is specified, the procedure will send a 
message to itself. If TOPGMQ(*PRV *) is specified, the procedure will send a 
message to the caller. 


Note: You should be aware of the following information when a procedure sends a 
message to the caller by specifying TOPGMQ(*PRV *). 

* When CLPROC4 and CLPROC2 send a message back to the callers, the 
message does not leave the containing program. The message is sent 
between procedures that are within the same program. If the objective is 
to send a message to the caller of the program (CLPGM1 in this example), 
specifying TOPGMQ(*PRV *) is not the right choice to use. 

* When CLPROC1 sends its message back to the caller, the Program Entry 
Procedure is skipped. The message is sent to CLPGM1 even though the 
caller is the PEP. When TOPGMQ(*PRV *) is specified, the PEP entry is 
not visible and not included in the send operation. If TOPGMOQ is specified 
in some other way, the PEP is visible to the sender. 


illustrates the results when CLPROC1, CLPROC2, and 
CLPROC4 each send a message back to the caller of each procedure. 
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CALL PGM(CLPGM1) 


CLPGM1 


OPM PROGRAM 


CALL PGM(CLPGM2) 


PROCEDURE 
_CL_PEP 


(in pgm CLPGM2) 


CALLPRC CLPROC1 


PROCEDURE 
CLPROC1 


(in pgm CLPGM2) 


CALLPRC CLPROC2 


PROCEDURE 
CLPROC2 


(in pgm CLPGM2) 


CALLPRC CLPROC4 


PROCEDURE 
CLPROC4 


(in pgm CLPGM2) 


RBAFN563-0 


Figure 4. Example of runtime call stack 
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CALL PGM(CLPGM1) 


CLPGM1 


OPM PROGRAM 


CALL PGM(CLPGM2) 


PROCEDURE 
CL_PEP 


(i n pgm CLPGM2) 


CALLPRC CLPROC1 


PROCEDURE 


SNDPGMMSG 
TOPGMQ(*PRV *) ... 


CLPROC1 


(in pgm CLPGM2) 


CALLPRC CLPROC2 


PROCEDURE 
CLPROC2 


(in pgm CLPGM2) SNDPGMMSG 


CALLPRC CLPROC4 


PROCEDURE 
CLPROC4 


SNDPGMMSG 
TOPGMQ(*PRV *) ... 


(in pgm CLPGM2) 


Figure 5. Example of TOPGMQ(*PRV *) 


Identifying the Base Entry by Name 


RBAFN564-0 


TOPGMQ(*PRV *) ... 


You can identify the base entry by providing the name of the OPM program or ILE 
procedure running in that entry. The name provided is either a simple name (one 


part) or a complex name (two or three parts). Following are descriptions of the 


simple and complex names: 


* Simple name 


A simple name is used to identify an OPM program or an ILE procedure. If the 
simple name you provide is 10 characters or less in length, it is determined by 
the system that the name is either an OPM program or an ILE procedure. The 
base is identified as the most recently called OPM program or ILE procedure by 


that name. 
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If the name is longer than 10 characters in length, it is determined by the system 
that the name is for an ILE procedure (OPM program names cannot be longer 
than 10 characters). The base is identified as the entry for the most recently 
called procedure by that name. Entries running OPM programs are not 
considered. 


See Figure 6 on page 214 for an example of sending a message using a simple 
name. In this example, CLPROC4 is sending a message to CLPROC2 and 
CLPROC2 is sending a message to CLPGM1. 


* Complex name 
A complex name consists of two or three parts. They are: 
— module name 


The module name is the name of the module into which the procedure was 
compiled. 


— program name 


The program name is the name of the program into which the procedure was 
bound. 


— procedure name 


When you want to uniquely identify the procedure to which you want to send 
the message, a complex name can be used in one of the following combinations: 


— procedure name, module name, program name 
— procedure name and module name 
— procedure name and program name 

You must specify the module name as *NONE. 


If you use a complex name, the base being identified cannot be running an OPM 
program. 


See Figure 7 on page 220 for an example of sending a message using a complex 
name. In this example, CLPROC4 is sending a message to CLPROC1 using a two 
part name consisting of (procedure name, program name). 


Rather than using the full OPM program name or the full ILE procedure name, 
you may use partial names. IBM provides online information concerning how to 
specify partial call stack entry names. Refer to the CL section of the Programming 
category in the iSeries Information Center for this information. 
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CALL PGM(CLPGM1) 


OPM PROGRAM 
CLPGM1 


CALL PGM(CLPGM2) 


PROCEDURE 
_CL_PEP 
(in pgm CLPGM2) 


CALLPRC CLPROC1 


PROCEDURE 
CLPROC1 
(in pgm CLPGM2) 


CALLPRC CLPROC2 


PROCEDURE 
CLPROC2 
(in pgm CLPGM2) 


SNDPGMMSG 
TOPGMQ (*SAME 
CLPGM1)... 


CALLPRC CLPROC4 


SNDPGMMSG TOPGMQ 
(*SAME CLPROC2) 


PROCEDURE 
CLPROC4 
(in pgm CLPGM2) 


Figure 6. Example of using a simple name 


RBAFN565-0 
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SNDPGMMSG TOPGMQ 


CALL PGM(CLPGM1) 


OPM PROGRAM 
CLPGM1 


CALL PGM(CLPGM2) 


PROCEDURE 
_CL_PEP 
(in pgm CLPGM2) 


CALLPRC CLPROC1 


PROCEDURE 
CLPROC1 — —— —]| 


(in pgm CLPGM2) 


CALLPRC CLPROC2 


PROCEDURE 
CLPROC2 
(in pgm CLPGM2) 


CALLPRC CLPROC4 


PROCEDURE 
CLPROC4 
(in pgm CLPGM2) 


(*SAME CLPROC1 *NONE CLPGM@) 


RBAFN566-0 


Figure 7. Example of using a complex name 


Program Boundary as Base 


The special value *PGMBDY is used by itself or with a program name to identify 
the PEP of a CL program. The entry for the PEP of the identified CL program then 
is the base entry. This option is useful when you want to send a message from 
within a CL procedure outside the boundary of the program which contains the 
procedure. 


Refer to Figure 8 on page 2221 for an example of sending a message using the 
special value *PGMBDY. In this example, CLPROC4 is sending a message directly 
to to CLPGM1 which is the caller of the containing program CLPGM2. CLPROC4 
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can do this without knowing which program called CLPGM2 or knowing the 
location of the PEP compared to the procedure sending the message. In this 
example, *PGMBDY is used without an accompanying program name specified. 
This means that the program whose boundary is to be identified is the program 
which contains the procedure that is sending the message. 


See Figure 9 on page 223) for an example of sending a message using the special 


value *PGMBDY and_a program name. The following programs and procedures are 
used in Foie San aageoot 


* CLPGM1 and CLPGM2. These are defined as in the previous examples. 

* CLPGM3. This is another ILE program 

* CLPROCA in CLPGMB. A message is sent from CLPROCA to the caller of 
CLPGM2. 


A message is sent from CLPROCA to the caller of CLPGM2 by using the special 
value *PGMBDY with program name CLPGM2. 


In this example, if the TOPGMQ parameter is specified as TOPGMQ(*PRV 
_CL_PEP), the message is sent to the caller of CLPGMS3 rather than the caller of 
CLPGM2. This occurs because the most recently called procedure by that name is 
the PEP for CLPGM3. 
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CALL PGM(CLPGM1) 


OPM PROGRAM 


CLPGM1 


CALL PGM(CLPGM2) 


PROCEDURE 


_CL_PEP 
(in pgm CLPGM2) 


CALLPRC CLPROC1 


PROCEDURE 
CLPROC1 


(in pgm CLPGM2) 


CALLPRC CLPROC2 


PROCEDURE 
CLPROC2 


(in pgm CLPGM2) 


CALLPRC CLPROC4 


SNDPGMMSG TOPGMQ 
(*PRV *PGMBDY) 


PROCEDURE 
CLPROC4 


(in pgm CLPGM2) 


Figure 8. Example 1 of using *PGMBDY 
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CALL PGM(CLPGM1) 


OPM PROGRAM 
CLPGM1 


| CALL PGM(CLPGM2) 


PROCEDURE 
_CL_PEP 
(in pgm CLPGM2) 


| CALLPRC CLPROC1 


PROCEDURE 
CLPROC1 
(in pgm CLPGM2) 


| CALLPRC CLPROC2 


PROCEDURE 
CLPROC2 
(in pgm CLPGM2) 


| CALLPRC CLPROC4 


PROCEDURE 
CLPROC4 
(in pgm CLPGM2) 


| CALL PGM(CLPGM3) 


PROCEDURE 
_CL_PEP 
(in pgm CLPGM3) 


CALLPRC CLPROCA 


PROCEDURE 
CLPROCA 
(in pgm CLPGM3) 


SNDPGMMSG TOPGMQ 
(*PRV *PGMBDY *NONE CLPGNM2) RBAFN568-0 


Figure 9. Example 2 of using *PGMBDY 


The special value *PGMBDY can also be used with an OPM program. If you 
specify an OPM program name with *PGMBDY, you have the same results as 
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when only the OPM program name is used. For example, TOPGMQ(*SAME 
*PGMBDY *NONE opmname) sends the message to the same place as 
TOPGMQ(*SAME opmname). 


The exception to this is when a message is sent to an OPM program that called 
itself recursively. TOPGMQ(*SAME pgmname) sends the message to the latest 
recursion level. However, TOPGMQ(*SAME *PGMBDY *NONE pgmname) sends 
the message to the first recursion level. shows how PGM1 is called and 
proceeds to call itself recursively two more times. At the third recursion level 
PGM1 calls PGM2. PGM2 then sends a message back to PGM1. If the program is 
sent using only the name PGM1, the message goes to the third recursion level of 
PGM1. If the program is sent using the name PGM1 in conjunction with the special 
value *PGMBDY, the message goes to the first recursion level of PGM1. 

Most Recently called Procedure as Base 


| CALL PGM(PGM1) 


: 


OPM PROGRAM 


PGM1 (level 1) 
| 
| CALL PGM(PGM1) 
OPM PROGRAM 
PGM1 (level 2) 
| 
| CALL PGM(PGM1) 
OPM PROGRAM 
PGM1 (level 3) 
| 
| CALL PGM(PGM2) 
OPM PROGRAM 
PGM2 
SNDPGMMSG SNDPGMMSG 
TOPGMQ(*SAME *PGMBDY *NONE PGM1) TOPGMQ(*SAME PGM1) 
RBAFN569-0 


Figure 10. Example 3 of using *PGMBDY 


Although you may not know the name of a procedure, you may want to send a 
message back to the most recently called procedure of an ILE program. The special 
value *PGMNAME is used with a ILE program name to use the base entry name 
as the name for the most recently called procedure of the identified program. The 
programs in this example are: 
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* CLPGM1 is an ILE program with procedures PROCA and PROCB. 
* CLPGM2 and CLPGM3 are both OPM programs. 


* CLPGMS is to send a message to CLPGM1 and does not know which procedure 
is the most recently called. 


The send is accomplished using the special value *PGMNAME and the program 
name CLPGM1. 


See Figure 11 on page 274, for an example of how to send a message using the 
special value *PGMNAME. 


The special value *PGMNAME is useful if you convert some CL programs, but not 
all CL programs, to ILE programs. For example, CLPGM1 is an OPM CL program; 
CLPGMS3 sent messages to CLPGM1 and specifies TOPGMQ(*SAME CLPGM1). If 
CLPGM1 is converted to ILE, only the SNDPGMMSG command in CLPGM3 
(OPM) works. CLPGM1 does not work because there was no entry in the call stack 
for CLPGM1. If you change the command to TOPGMQ(*SAME *PGMNAME 
*NONE CLPGM1), CLPGM3 sends messages successfully to CLPGM1 regardless of 
the names you may have used for procedure names. 


The special value *PGMNAME can also be used in with an OPM program name. 
In this case the effect is the same as if you just used the name. For example, 
TOPGMQ(*SAME *PGMNAME *NONE opmpgm) sends the message to the same 
place as TOPGMQ(*SAME opmpgm). The use of *PGMNAME should be 
considered when you cannot determine whether the message is being sent to an 
OPM program name or and ILE program name. 


Using a Control Boundary as a Base 


You can identify the base entry as the one at the nearest control boundary by using 
the special value *CTLBDY. A control boundary exists between two call stack 
entries if the two entries are running in two different activation groups. The one 
identified by using this special value is running in the same activation group as 
the entry that is sending the message. 


See Figure 12 on page 2271 for an example of sending a message using the special 
value *CTLBDY. The three programs in this example (CLPGM1, CLPGM2, and 
CLPGMsS) are all ILE programs. CLPGM1 runs in activation group AG1 while both 
CLPGM2 and CLPGMS3 run in activation group AG2. In this example, PROC3A 
sends a message back to the entry that immediately precedes the boundary for 
AG2. 
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CALL PGM(CLPGM1) 


PROCEDURE 
_CL_PEP 


CALLPRC PROCA 


PROCEDURE 
PROCA 
(in pgm C 


LPGM1) 


CALLPRC PROCB 


PROCEDURE 
(>, PROCB 


(in pgm C 


LPGM1) 


CALL PGM(CLPGM2) 


CLPGM2 


OPM PROGRAM 


CALLPGM(CLPGM3) 


CLPGM3 


SNDPGMMSG TOPGMQ 


OPM PROGRAM 


(*SAME *PGMNAME *NONE 
CLPGM1)... 


Figure 11. Example of runtime call stack 
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| CALL PGM(CLPGM1) 
Activation Group Ag1l | 


PROCEDURE 

_CL_PEP 

(in pgm CLPGM1) 
| 


| CALLPRC PROCI1A 


PROCEDURE 

PROC1A 

(in pgm CLPGM1) 
| 


CALL PGM(CLPGM2) 


Activation Group Ag2 I 


PROCEDURE 

_CL_PEP 

(in pgm CLPGM2) 
| 


| CALLPRC CLPROC2A 


PROCEDURE 
PROC2A 
(in pgm CLPGM2) 
| 
| CALL PGM(CLPGM3) 


PROCEDURE 

_CL_PEP 

(in pgm CLPGM3) 
| 


: 


PROCEDURE 
PROC3A 
(in pgm CLPGM3) 


CALLPRC PROC3A 


SNDPGMMSG TOMSGQ 
(*PRV *CTLBDY) 


RBAFN571-0 


Figure 12. Example of using *CTLBDY 


Considerations for Service Programs 
Previous discussions apply to both ILE programs and ILE service programs. The 


most important difference between an ILE program and an ILE service program is 
related to message handling. The service program does not have a PEP. 
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The PEP is not necessary for any of the options used to identify a base entry. An 
exception to this is when the name _CL_PEP is used explicitly. For example, 
TOPGMQ(*PRV *PGMBDY) always sends a message to the caller of the ILE 
program or service program. If it is an ILE program, the PEP is identified as the 
base by the *PGMBDY value. If it is an ILE service program, the entry for the first 
procedure called in the service program is identified by the *PGMBDY value. 


Receiving Messages in a CL Procedure or Program 


Use the Receive Message (RCVMSG) command to receive messages from a 
message queue for your procedure or program. Messages can be received in the 
following ways: 


By message type. You can specify that all types or that a specific type can be 
received (MSGTYPE parameter). New messages (those that have not been 
received in the procedure or program) are received in a first-in-first-out (FIFO) 
order. However, ESCAPE type messages are received in last-in-first-out (LIFO) 
order. 


By message reference key. You can do one of the following: 


— Receive a message using its message reference key. The system assigns a 
message reference key to each message on a message queue and passes the 
key as variable data because it is unprintable. You must declare this variable 
in your CL procedure or program (DCL command). You must specify on the 
RCVMSG command the CL variable through which the key is to be passed 
(MSGKEY parameter). 

— Receive the next message on a message queue following the message with a 
specified message reference key. In addition to specifying the MSGKEY 
parameter, you must specify MSGTYPE(*NEXT). 

— Receive the message on a message queue that is before a message with a 
specified message reference key. In addition to specifying the MSGKEY 
parameter, you must specify MSGTYPE(*PRV). 

By its location on the message queue. You must specify MSGTYPE(*FIRST) for 

the first message on the message queue; specify MSGTYPE(*LAST) for the last. 

By both message type and message reference key (MSGTYPE and MSGKEY 

parameters). 


To receive a message, you can specify: 


Message queue. Where the message is to be received from. 


Message type. Either a specific message type can be specified or all types can be 
specified. 

Whether to wait for the arrival of a message. After the wait is over and no 
message is received, the CL variables requested to be returned are filled with 
blanks (or zeros if numeric) and control returns to the procedure or program 
running the RCVMSG command. 


Whether to remove the message from the message queue after it is received. If it 
is not removed, it becomes an old message on the message queue and can only 
be received again (by a procedure) through its message reference key. However, 
if messages on the message queue are reset to new messages through the 
CHGMSGQ command, you do not have to use the message reference key to 
receive the message. Note that inquiry_messages that have already been replied 
to_are not reset to a new status. (See m 
for more information.) 


CCSID to convert to. Specifies the CCSID that you want your message text 
returned in. 
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* A group of CL variables into which the following information is placed (each 
corresponds to one variable): 


— Message reference key of the message in the message queue (character 
variable, 4 characters) 


— Message (character variable, length varies) 


— Length of message, including length of substitution variable data (decimal 
variable, 5 decimal positions) 


— Message online help information (character variable, length varies) 


— Length of message help, including length of substitution variable data 
(decimal variable, 5 decimal positions) 


— Message data for the substitution variables provided by the sender of the 
message (character variable, length varies) 


— Length of the message data (decimal variable, 5 decimal positions) 

— Message identifier (character variable, 7 characters) 

— Severity code (decimal variable, length of 2) 

— Sender of the message (character variable, minimum of 80 characters) 

— Type of message received (character variable, 2 characters long) 

— Alert option of the message received (character variable, 9 characters) 

— Message file that contains the predefined message (character variable, 10 
characters) 

— Message file library name that contains the message file used to receive the 
message (character variable, 10 characters) 

— Message file library name that contains the message file used to send the 
message (character variable, 10 characters) 


— Message data CCSID is the coded character set identifier associated with the 
replacement data returned (decimal variable, 5 decimal positions) 


— Text data CCSID is the coded character set identifier associated with the text 
returned by the Message and the Message help parameters (decimal variable, 
5 decimal positions) 


RCVMSG MSGQ(QGPL/INVN) MSGTYPE(*ANY) MSG(&MSG) 


The message received is placed in the variable &MSG. *ANY is the default value 
on the MSGTYPE parameter. 


When working with the call stack entry message queue of an ILE procedure 
written in a language other than CL, it is possible to receive an exception message 
(Escape or Notify) when the exception is not yet handled. The RCVMSG command 
can be used to both receive a message and indicate to the system that the 
exception has been handled. 


This can be controlled by using the RMV keyword. If *NO is specified for this 
keyword, the exception is handled and the message is left on the message queue as 
an old message. If *KEEPEXCP is specified, the exception is not handled and the 
message is left on the message queue as a new message. If *YES is specified, the 
exception message is handled and the message is removed from the message 
queue. 


The RTNTYPE keyword can be used to determine if the message received is an 
exception message, and if so, whether the exception has been handled. 
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Program Stac 


k 


Request Messages 

Receiving request messages is a method for your CL procedure or program to 
process CL commands. For example, your procedure or program can obtain input 
from a display station and handle the messages that result from the analysis and 
processing of the program. Usually, request messages are received from the 
external message queue (*EXT) of the job. For batch jobs, the requests received are 
those read from the input stream. For interactive jobs, the requests received are 
those the display station user enters one at a time on the Command Entry display. 
For example, CL commands are requests that are received by the IBM-supplied CL 
processor. 


Your procedure or program must define the syntax of the data in the request 
message, interpret the request, and diagnose any errors. While the request is being 
analyzed or the request function is being run, any number of errors can be 
detected. As a result of these errors, messages are sent to the call message queue 
for the procedure or program. The procedure or program handles these messages 
and then receives the next request message. Thus, a request processing cycle is 
defined; a request message is received, the request is analyzed and run by your 
procedure or program with resulting messages displayed, and the next request 
received. If there are no more request messages to be received in a batch job, an 
escape message is sent to your procedure or program to indicate this. 


More than one OPM program or ILE procedure of a job can receive request 
messages for processing. The requests received by more recent program calls are 
considered to be nested within those received by higher level program calls. The 
request processing cycles at each nesting level are independent of each other. 
Within an ILE program, one or more procedures within that program can be 
receiving request messages. If more than one procedure is processing requests than 
the nesting occurs within the same ILE program and the nesting levels remain 
independent. 


The following diagram shows how request messages are processed by QCMD: 


Job Message Queue 


Program QCMD 
Oo. 


° 


. 


CALLCPP 


RCVMSG MSGTYPE(*RQS) 


PGMQ(*EXT) 


Program CPP 


SNDPGMMSG TOPGMQ(*PRV) 
MSGTYPE(*DIAG) 


; 6 | a 
SNDPGMMSG TOPGMQ(*PRV) 


MSGTYPE(*ESCAPE) 


3 | Command Entry Display 2 | 
“EXT +» Commandrequest 1 
Diagnosticmessage 1 
nr QCMD program message queue ? 
Command request 1 < ‘s 
{ Diagnostic message 1 Diagnostic messagen 
Escape message 
—> ° 
Diagnosticmessagen 8 | me SD) 
p Escapemessage 


CPP 9 | 


; 


The CL processor QCMD receives a request message from *EXT. 


RSLF166-1 


2 | If there is no request message on *EXT, the Command Entry display is 
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displayed. The display station user enters a command on the display. 
When the command is entered, it is placed on *EXT as a request message. 


| 


The command is then moved to the end of the QCMD call message queue 
and is passed from there to QCMD. 


The command is analyzed and its command processing program (CPP) is 
called. 


The command processing program sends diagnostic messages to the call 
message queue for QCMD. 


Then the command processing program sends an escape message to the 
call message queue for QCMD. The escape message notifies QCMD that 
diagnostic messages are on the queue and that QCMD should end 
processing of the CPP. 


QCMD is monitoring for the arrival of a request-check (CPF9901) or 
function-check (CPF9999) escape message. QCMD then tries to receive the 
next request message. If a request processor receives message CPF9901 or 
CPF9999, it should run a Reclaim Resources (RCLRSC) command. The 
request processor should also monitor for messages CPF1907 (end. request) 
and CPF2415 (which indicates that the user pressed F3 or F12 on the 
Command Entry display). 


8 Because a request message was being processed, all the messages on the 
call message queue for QCMD are written to the Command Entry display, 
which then prompts the display station user for another command. 


9 | The previous request message (command) and its associated messages are 
contained in the job log according to the message logging level specified 
for the job. For more information, see 


Writing Request-Processing Procedures and Programs 
Specifying a CL procedure as a request processor within a program has many 
advantages. The following list specifies three advantages: 


* Processes request messages as described in ’Requ 


* Allows the use of the End Request (ENDRQS) command, which can be used 
from the System Request menu or as part of the disconnect job function. 


* Allows filtering of messages to occur. 


To become a request-processor procedure or program, your procedure or program 
must include the Send Program Message (GSNDPGMMSG) and Receive Message 
(RCVMSG) commands. For example, the following commands would allow a 
procedure or program to become a request processor: 


SNDPGMMSG MSG('Request Message') TOPGMQ(*EXT) MSGTYPE(*RQS) 
RCVMSG PGMQ(*EXT) MSGTYPE(*RQS) RMV(*NO) 


The request message is received from PGMQ *EXT. When any request message is 
received, it is moved (actually, it is removed and resent) to the call message queue 
of the procedure or program that specified the RCVMSG command. Therefore, the 
correct call message queue must be used when the message is removed. 


If the request message is removed using the message reference key (MRK), you 
should obtain the MRK from the KEYVAR keyword of the RCVMSG command 
and not the SNDPGMMSG command. (The MRK changes when receiving a request 
message.) You must specify RMV(*NO) on the RCVMSG command because the 
procedure or program is not a request processor if the request message is removed 
from the call message queue. 
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The procedure or program is identified as a request processor when the request 
message is received. While the procedure or program is a request processor, other 
called procedures or programs can be ended using option 2 (End request) on the 
System Request menu. The request-processor procedure or program should include 
a monitor for message CPF1907 (MONMSG command). This is necessary because 
the end request function (from either option 2 on the System Request menu or the 
End Request command) sends this message to the request processor. 


The procedure or program remains a request processor until the procedure ends 
(either normally or abnormally) or until a RMVMSG command is run to remove all 
the request messages from the request-processor’s call message queue. For 
example, the following command removes all request messages from the message 
queue and, therefore, ends request processing: 


RMVMSG CLEAR(*ALL) 


Call the QCAPCMD API and specify the message retrieve key to have the OS/400 
command analyzer to process a request message for an OS/400 command. You can 
get the message retrieve key when you receive the request message. Process 
Commands (QCAPCMD) will update the request message in the job log and add 
any new value supplied. QCAPCMD also hides any parameter values, such as 
passwords, that are to hidden in the job log. The system will not update the 
request message in the job log when one of two conditions exists. 


* Using the Execute Command (QCMDEXC or QCAEXEC) APIs. 
* Failing to supply a message retrieve key to QCAPCMD. 


Determining if a Request-Processor Exists 
To determine if a job has a request processor, display the job’s call stack. Use either 
option 11 on the Display Job (DSPJOB) or Work with Job (WRKJOB) command, or 
select option 10 for the job listed on the WRKACTIJOB display. If a number is 
shown in the request level column on the display of the job’s call stack, the 
program or ILE procedure associated with the number is a request-processor. In 
the following example, both QCMD and QTEVIREF are request processors: 

ie 


>) 
Display Call Stack 
System: S0000000 
Job:  WS31 User: QSECOFR Number: 000173 
Type options, press Enter. 
5=Display details 
Request Program or 
Opt Level Procedure Library Statement Instruction 
QCMD QSYS 01DC 
1 QCMD QSYS 016B 
QTECADTR QSYS 0001 
2 QTEVIREF QSYS 02BA 
Bottom 
F3=Exit F1Q=Update stack F1l1=Display activation group  F12=Cancel 
F17=Top F18=Bottom 
Ne e/ 


The following is an example of a request-processing procedure: 
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PGM 
SNDPGMMSG MSG('Request Message') TOPGMQ(*EXT) MSGTYPE(*RQS) 
RCVMSG PGMQ(*EXT) MSGTYPE(*RQS) RMV(*NO) 


CALL  PGM(PGMONE) 
MONMSG MSGID(CPF1907) 


RMVMSG CLEAR(*ALL) 
CALL PGM(PGMTWO) 


ENDPGM 


The first two commands in the procedure make it a request processor. The 
procedure remains a request processor until the RMVMSG command is run. A 
Monitor Message command is placed after the call to program PGMONE because 
an end request may be sent from PGMONE to the request-processor. If monitoring 
is not used, a function check would occur for an end request. No message monitor 
is specified after the call to PGMTWO because the RMVMSG command ends 
request processing. 


If an end request is attempted when no request-processing procedure or program 
is called, an error message is issued and the end operation is not performed. 


Note: In the sample programs, the RCVMSG command uses the minimal number 
of parameters needed to become a request processor. You need to say you 
want to receive a request message but do not want to remove it. You also 
need to identify the specific call queue from which the message request 
originated. Other parameters can be added as necessary. 


Retrieving Messages in a CL Procedure 


You can use the Retrieve Message (RTVMSG) command to retrieve the text of a 
message from a message file into a variable. RT'VMSG operates on predefined 
message descriptions. You can specify the message identifier and message file 
name in addition to the following: 


* CCSID to convert to. Specifies the coded character set identifier that you want 
your message text and data returned in. 


* Message data fields. The message data for the substitution variables. 


* Message data CCSID. Specifies the coded character set identifier that the 
supplied message data is to be considered in. 


* A group of CL variables into which the following information is placed (each 
corresponds to one variable): 


— Message (character variable, length varies) 


— Length of message, including length of substitution variable data (decimal 
variable, 5 decimal positions) 


— Message online help information (character variable, length varies) 


— Length of message help, including length of substitution variable data 
(decimal variable, 5 decimal positions) 


— Severity code (decimal variable, 2 decimal positions) 
— Alert option (character variable, 9 characters) 
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— Log problem in the service activity log (character variable, 1 character) 
— Message data CCSID is the coded character set identifier associated with the 
replacement data returned (decimal variable, 5 decimal positions) 


— Text data CCSID is the coded character set identifier associated with the text 
returned by the Message and the Message help parameters (decimal variable, 
5 decimal positions) 


For example, the following command adds the message description for the 
message USR1001 to the message file USRMSG: 


ADDMSGD MSGID(USR1001) MSGF(QGPL/USRMSG) + 
MSG('File &1 not found in library &2') + 
SECLVL('Change file name or library name') + 
SEV(40) FMT((*CHAR 10) (*CHAR 10)) 


The following commands result in the substitution of the file name INVENT in the 
10-character variable &FILE and the library name QGPL in the 10-character 
variable &LIB in the retrieved message USR1001. 


DCL &FILE TYPE(*CHAR) LEN(10) VALUE(INVENT) 

DCL &LIB TYPE(*CHAR) LEN(10) VALUE(QGPL) 

DCL 8A TYPE(*CHAR) LEN(20) 

DCL &MSG TYPE(*CHAR) LEN(50) 

CHGVAR VAR(&A) VALUE(&FILE| |&LIB) 

RTVMSG MSGID(USR1001) MSGF(QGPL/USRMSG) + 
MSGDTA(&A) MSG (&MSG) 


The data for &1 and &2; is contained in the procedure variable &A, in which the 
values of the procedure variables &FILE and &LIB have been concatenated. The 
following message is placed in the CL variable &MSG: 


File INVENT not found in library QGPL 


If the MSGDTA parameter is not used in the RTVMSG command, the following 
message is placed in the CL variable &MSG: 


File not found in library 


After the message is placed in the variable &MSG, you could do the following: 
* Send the message using the SNDPGMMSG command 

* Use the variable as the text for a message line in DDS (M in position 38) 

* Use a message subfile 

* Print or display the message 


Note: You cannot retrieve the message text with the variable names that are 
included in the text. The system intends on RTVMSGD to return a sendable 
message. 


Removing Messages from a Message Queue 


Messages are held on a message queue until they are removed by a Remove 
Message (RMVMSG) command, Clear Message Queue (CLRMSGQ) command, the 
RMV parameter on the Receive Message (RCVMSG) and Send Reply (SNDRPY) 
commands, the remove function keys of the Display Messages display, or the clear 
message queue option on the Work with Message Queue display. You can remove: 


* A single message 

* All messages 

* All except unanswered messages 
* All old messages 
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* All new messages 
* All messages from all inactive programs 


To remove a single message using the RMVMSG command or a single old message 
using the RCVMSG command, you specify the message reference key of the 
message to be removed. 


Note: The message reference key can also be used to receive a message and to 
reply to a message. 


If you remove an inquiry message that you have not answered, a default reply is 
sent to the sender of the message and the inquiry message and the default reply 

are removed. If you remove an inquiry message that you have already answered, 
both the message and your reply are removed. 


To remove all messages for all inactive programs and procedures from a user’s job 
message queue, specify *~ALLINACT for the PGMQ parameter and *ALL for the 
CLEAR parameter on the RMVMSG command. If you want to print your job log 
before you remove all the inactive messages, use the Display Job Log 
(DSPJOBLOG) command and specify *PRINT for the OUTPUT parameter. 


When working with a call message queue of an ILE procedure, it is possible that 
an exception message for unhandled exceptions is on the queue at the time the 
RMVMSG command is run. The RMVEXCP keyword of this command can be used 
to control actions for messages of this type. If *YES is specified for this keyword, 
the RMVMSG command causes the exception to be handled and the message to be 
removed. If *NO is specified, the message is not removed. As a result, the 
exception is not handled. 


The following RMVMSG command removes a message from the user message 
queue JONES. The message reference key is in the CL variable &MRKEY. 
DCL &MRKEY TYPE(*CHAR) LEN(4) 


RCVMSG MSGQ(JONES) RMV(*NO) KEYVAR(&MRKEY) 
RMVMSG MSGQ(JONES) MSGKEY (&MRKEY) 


The following RMVMSG command removes all messages from a message queue. 
RMVMSG CLEAR(*ALL) 


Note: The maximum number of messages on a user message queue or a work 
station message queue is 65 535 for each type of message sent. For example, 
65 535 diagnostic messages can be on the queue; 65 535 completion 
messages can be on the queue, and so on. For a call message queue or the 
*EXT queue, there is no restriction on the maximum number of messages 


per type. 


Monitoring for Messages in a CL Program or Procedure 


You can monitor for escape, notify, and status messages that are sent to your CL 
procedure’s or program’s call message queue by the commands in your procedure 
or program or by commands in another procedure or program. The Monitor 
Message (MONMSG) command monitors the messages sent to the call message 
queue for the conditions specified in the command. If the condition exists, the CL 
command specified on the MONMSG command is run. The logic involved with 
the MONMSG command is as follows: 
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Escape Messages: Escape messages are sent to tell your procedure or program of 
an error condition that forced the sender to end. By monitoring for escape 
messages, you can take corrective actions or clean up and end your procedure or 
program. 


Status or Notify Messages Status and notify messages are sent to tell your 
procedure or program of an abnormal condition that is not serious enough for the 
sender to end. By monitoring for status or notify messages, your procedure or 
program can detect this condition and not allow the function to continue. 


You can monitor for messages using two levels of MONMSG commands: 


* Procedure level: You can monitor for an escape, notify, or status message sent by 
any command in your procedure by specifying the MONMSG command 
immediately following the last declare command in your CL procedure or 
program. This is called a procedure-level MONMSG command. You can use as 
many as 100 procedure-level MONMSG commands in a procedure or OPM 
program. (A CL procedure or OPM program can contain a total of 1000 
MONMSG commands.) This lets you handle the same escape message in the 
same way for all commands. The EXEC parameter is optional, and only the 
GOTO command can be specified on this EXEC parameter. 
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1 Information 
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If a status message is sent 
to *EXT, it cannot be | nanets 
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Repeat : Program Ends, 
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Again Next Command Sent to Caller 


RV3W196-1 


Specific command level: You can monitor for an escape, notify, or status message 
sent by a specific command in your procedure or program by specifying the 
MONMSG command immediately following the command. This is called a 
command level MONMSG command. You can use as many as 100 
command-level MONMSG commands for a single command. This lets you 
handle different escape messages in different ways. 
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To monitor for escape, status, or notify messages, you must specify, on the 
MONMSG command, generic message identifiers for the messages in one of the 
following ways: 


* pppmmnn 


Monitors for a specific message. For example, MCH1211 is the message identifier 
of the zero divide escape message. 


* pppmm00 


Monitors for any message with a generic message identifier that begins with a 
specific licensed program (ppp) and the digits specified by mm. For example, 
CPF5100 indicates that all notify, status, and escape messages beginning with 
CPF51 are monitored. 


* ppp000d 


Monitors for every message with a generic message identifier that begins with a 
specific licensed program (ppp). For example, CPF0000 indicates that all notify, 
status, and escape messages beginning with CPF are monitored. 


Note: Do not use MONMSG CPF0000 when doing system function, such as install or 
saving or restoring your entire system, since you may lose important 
information. 


° CPF9999 


Monitors for function check messages for all generic message identifiers. If an 
error message is not monitored, it becomes a CPF9999 (function check). 


Note: Generally, when monitoring, your monitor also gets control when notify and 
status messages are sent. 


In addition to monitoring for escape messages by message identifier, you can 
compare a character string, which you specify on the MONMSG command, to data 
sent in the message. For example, the following command monitors for an escape 
message (CPF5101) for the file MYFILE. The name of the file is sent as message 
data. 


MONMSG MSGID(CPF5101) CMPDTA(MYFILE) EXEC(GOTO EOJ) 


The compare data can be as long as 28 characters, and the comparison starts with 
the first character of the first field of the message data. If the compare data 
matches the message data, the action specified on the EXEC parameter is run. 


The EXEC parameter on the MONMSG command specifies how an escape message 
is to be handled. Any command except PGM, ENDPGM, IF, ELSE, DCL, DCLF, 
ENDDO, and MONMSG can be specified on the EXEC parameter. You can specify 
a DO command on the EXEC parameter, in which case, the commands in the do 
group are run. When the command or do group (on the EXEC parameter) has been 
run, control returns to the command in your procedure or program that is after the 
command that sent the escape message. However, if you specify a GOTO or 
RETURN command, control does not return. If you do not specify the EXEC 
parameter, the escape message is ignored and your procedure continues. 


The following shows an example of a Change Variable (CHGVAR) command being 
monitored for a zero divide escape message, message identifier MCH1211: 


CHGVAR VAR(&A) VALUE(&A / &B) 
MONMSG MSGID(MCH1211) EXEC(CHGVAR VAR(&A) VALUE(1)) 


The value of the variable &A is changed to the value of &A divided by &B. If &B 
equals 0, the divide operation cannot be done and the zero divide escape message 
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is sent to the procedure. When this happens, the value of &A is changed to 1 (as 
specified on the EXEC parameter). You may also test &B for zero, and only 
perform the division if it is not zero. This is more efficient than attempting the 
operation and monitoring for the escape message. 


In the following example, the procedure monitors for the escape message CPF9801 
(object not found message) on the Check Object (CHKOBJ) command: 

PGM 

CHKOBJ LIB1/PGMA *PGM 

MONMSG MSGID(CPF9801) EXEC(GOTO NOTFOUND) 

CALL LIB1/PGMA 

RETURN 
NOTFOUND: CALL FIX001 /* PGMA Not Found Routine */ 

ENDPGM 


The following CL procedure contains two CALL commands and a procedure-level 
MONMSG command for CPF0001. (This escape message occurs if a CALL 
command cannot be completed successfully.) If either CALL command fails, the 
procedure sends the completion message and ends. 

PGM 

MONMSG MSGID(CPF0001) EXEC(GOTO ERROR) 

CALL PROGA 

CALL PROGB 

RETURN 
ERROR: SNDPGMMSG MSG('A CALL command failed') MSGTYPE(*COMP) 

ENDPGM 


If the EXEC parameter is not coded on a procedure-level MONMSG command, any 
escape message that is handled by the MONMSG command is ignored. If the 
escape message occurs on any command except the condition of an IF command, 
the procedure or program continues processing with the command that would 
have been run next if the escape message had not occurred. If the escape message 
occurs on the condition of an IF command, the procedure or program continues 
processing as if the condition on the IF command were false. The following 
example illustrates what happens if an escape message occurs at different points in 
the procedure: 

PGM 

DCL 8A TYPE(*DEC) LEN(5 0) 

DCL &B TYPE(*DEC) LEN(5 0) 

MONMSG MSGID(CPFOQ01 MCH1211) 

CALL PGMA PARM(8A &B) 

IF (8A/&B *EQ 5) THEN(CALL PGMB) 

ELSE CALL PGMC 

CALL PGMD 

ENDPGM 


Depending on where an escape message occurs, the following happens: 

* If CPFO001 occurs on the call to PGMA, the procedure resumes processing on 

the IF command. 

If MCH1211 (divide by 0) occurs on the IF command, the IF condition is 

considered false, and the procedure resumes processing with the call to PGMC. 

* If CPFO001 occurs on the call to PGMB or PGMC, the procedure resumes 
processing with the call to PGMD. 


* If CPFO001 occurs on the call to PGMD, the procedure resumes processing with 
the ENDPGM command, which causes a return to the calling procedure. 


You can also monitor for the same escape message to be sent by a specific 
command in your procedure or program and by another command. This requires 
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two MONMSG commands. One MONMSG command follows the command that 
needs special handling for the escape message; for that command, this MONMSG 
command is used when the escape message is sent. The other MONMSG 
command follows the last declare command so that for all other commands, this 
MONMSG command is used. 


MONMSG commands apply only to the CL procedure or OPM program in which 
they are coded. MONMSG commands from one procedure do not apply to another 
procedure even though both are part of the same program. IBM provides online 
help that contains a list of the escape, notify, and status messages that are issued 
for CL commands. Refer to the CL section of the Programming category in the 
iSeries Information Center for this information. You should also keep a list of all 
messages that you have defined. 


Note: The above paragraph is not true for ILE procedures because of the way 
messages percolate. The system requires MONMSG to handle any escape 
message that is sent to a procedure. Otherwise, the message percolates up 
the call stack until it finds a procedure that has a MONMSG to handle it or 
hits a control boundary. 


Default Handling 


Many escape messages can be sent to a procedure that calls commands, programs, 
and procedures. You will not want to monitor and handle all of the messages. 
However, you may want to monitor and handle the escape messages which pertain 
to the function of your procedure. The system provides default monitoring and 
handling of any messages you do not monitor. 


Default handling assumes that an error has been detected in a procedure. If you 
are debugging the procedure, the message is sent to your display station. You can 
then enter commands to analyze and correct the error. If you are not debugging 
the procedure, the system performs a message percolation function. 


Message percolation is a two-step function that does the following: 
* Moves the escape message one step earlier in the call stack. 
* Checks to see if the procedure has a MONMSG command for the escape. 


If the procedure has a MONMSG command for the escape, the message percolation 
action stops, and the system takes the action that is specified by the MONMSG 
command. Message percolation continues until either finding a MONMSG 
command, or until finding the nearest control boundary. This means that the 
escape message does not percolate across control boundaries. 


The function check processing begins by finding the control boundary before 
finding a procedure with a MONMSG command which applies to the message. 
The system considers action on the original escape exception complete. The system 
then sends the function check message (CPF9999) to the procedure that was the 
target of the original escape. If that procedure has a MONMSG for the function 
check message, then it takes the action that is specified by that command. 
Otherwise, the system sends an inquiry message to the workstation operator if the 
job is an interactive job. The workstation operation can reply with one of the 
following replies: 


R Retry the failing command in the procedure. 
I Ignore the message. Continue processing at the next command in the 
procedure. 
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C Cancel the procedure and percolate the function check to the next previous 
procedure on the call stack. 


D Dump the call stack entry for the failing procedure, cancel the procedure, 
and percolate the function check to the next previous procedure on the call 
stack. This is the default action if entering no reply, or if the job is a batch 
job. 


The system does not percolate the function check across the control boundary. If 
any reply causes the function check to move across an activation group boundary, 
this stops further action on the function check. The system cancels all procedures 
up to the activation group boundary, and sends the escape message CEE9901 to the 
prior call stack entry. 


You can monitor for function-check escape messages so that you can either: 
* Clean up and end the procedure 
* Continue with some other aspect of your procedure 


Note: If the message description for the unmonitored escape specifies a default 
action, the default handling program is called before the function check 
message is sent. When the default handling program returns, function check 
processing begins. 


Notify Messages 


Besides monitoring for escape messages, you can monitor for notify messages that 
are sent to your CL procedure’s or program’s call message queue by the 
commands in your procedure or program or by the programs and procedures it 
calls. Notify messages are sent to tell your procedure or program of a condition 
that is not typically an error. By monitoring for notify messages, you can specify an 
action different from what you would specify if the condition had not been 
detected. Very few IBM-supplied commands send notify messages. 


Monitoring for and handling notify messages is similar to monitoring for and 
handling escape messages. The difference is in what happens if you do not 
monitor for and handle notify messages. Notify messages are also percolated from 
procedure to procedure within the boundary of the activation group. If the 
activation group boundary is reached without a MONMSG command being found 
for it, the default reply is automatically returned to the sender of the notify 
message and the sender is allowed to continue processing. Unlike escape messages, 
unmonitored notify messages are not considered an indication of an error in your 
procedure or program. 


Status Messages 


You can monitor for status messages that are sent by the commands in your CL 
procedure or by the programs or procedures it calls. Status messages tell your 
procedure the status of the work performed by the sender. By monitoring for 
status messages, you can prevent the sending program or procedure from 
proceeding with any more processing. 


No message information is stored in a message queue for status messages. 
Therefore, a status message cannot be received. 


If a status message is not monitored for, it is percolated like escape and notify 
messages are. If the activation group boundary is reached without a MONMSG 


command being found, action on the message is considered complete and control 
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is returned to the sender of the message to continue processing. Status messages 
are often sent to communicate normal conditions that have been detected where 
processing can continue. 


Status messages sent to the external message queue are shown on the interactive 
display, informing the user of a function in progress. For example, the Copy File 
(CPYF) command sends a message informing the user that a copy operation is in 
progress. 


Only predefined messages can be sent as status messages; immediate messages 
cannot be sent. You can use the system-supplied message ID, CPF9898, and supply 
message data to send a status message if you do not have an existing message 
description. 


When the function is completed, your procedure or program should remove the 
status message from the interactive display. The message cannot be removed using 
a command, but sending another status message to *EXT with a blank message 
gives the appearance of removing the message. The system-supplied message ID 
CPI9801 can be used for this purpose. When control returns to the OS/400 
program, the *STATUS message may be cleared from line 24, without sending the 
CPI9801 message. The following example shows a typical application of message 
IDs CPF9898 and CPI9801: 
SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) + 

MSGDTA('Function xxx being performed') + 

TOPGMQ(*EXT) MSGTYPE(*STATUS) 


e /* Your processing function */ 


SNDPGMMSG MSGID(CP19801) MSGF(QCPFMSG) + 
TOPGMQ(*EXT) MSGTYPE(*STATUS) 


Preventing the Display of Status Messages 


You cannot prevent commands from sending status messages, but you can prevent 
the status messages from being displayed at the bottom of the screen. 


There are two preferred ways to prevent the status messages from being shown: 

* Change User Profile (CHGUSRPRF) command 
You can change your user profile so that whenever you sign on using that 
profile, status messages are not shown. To do this, use the CHGUSRPRF 
command and specify *NOSTSMSG on the User Option (USROPT) parameter. 

* Change Job (CHGJOB) command 
You can change the job you are currently running so that status messages are 
not shown. To do this, use the CHGJOB command and specify *NONE on the 
Status Message (STSMSG) parameter. You can also use the CHGJOB command to 
see status messages by specifying *NORMAL on the STSMSG parameter. 


A third alternative, however less preferred, is to use the Override Message File 


(OVRMSGF) command and change the status message identifiers to a blank 
message. 
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Break-Handling Programs 


A break-handling program is one that is automatically called when a message 
arrives at a message queue that is in *BREAK mode. You must specify the name of 
both the program and the break delivery name on the same Change Message 
Queue (CHGMSGQ) command. Although you specify the program on the 
CHGMSGQ command, it is one or more procedures within the program that 
processes the message. A procedure within this program must run a Receive 
Message (RCVMSG) command to receive the message. To receive and handle the 
message, the user-defined program called to handle messages for break delivery 
receives parameters. Specifically, the first procedure to run within the program 
receives these parameters. The parameters identify the message queue and the 
message reference key (MRK) of the message that is causing the break. IBM 
provides an online list for the parameters of the Break Handling exit program. 
Refer to the CL section of the Programming category of the iSeries Information 
Center for the list. If the system calls a break-handling program, it interrupts the 
job that has the message queue in break mode. When the break-handling program 
ends, the original program resumes processing. 


The following program (PGMA), which consists of only this one procedure, is an 
example of a break-handling program. 
PGM PARM(&MSGQ &MSGLIB &MRK) 
DCL VAR(&MSGQ) TYPE(*CHAR) LEN(10) 
DCL VAR(&MSGLIB) TYPE(*CHAR) LEN(10) 
DCL VAR(&MRK) TYPE(*CHAR) LEN(4) 
DCL VAR(&MSG) TYPE(*CHAR) LEN(75) 
RCVMSG + MSGQ(&MSGLIB/&MSGQ) MSGKEY(&MRK) + 
MSG (&MSG) 


ENDPGM 


After the break-handling program is created, running the following command 
connects it to the QSYSMSG message queue. 


CHGMSGQ MSGQ(QSYS/QSYSMSG) DLVRY(*BREAK) PGM(PGMA) 


Notes: 


1. When messages are handled, they should be removed from the message queue. 
When a message queue is put in break mode, any message on the queue will 
cause the break-handling program to get called. 


2. The procedure or program receiving the message should not be coded with a 
wait-time other than zero to receive a message. You can specify a value other 
than zero for the wait parameter with the Receive Message (RCVMSG) 
command. The message arrival event cannot be handled by the system while 
the job is running a break-handling event. 


An example of a break-handling program is to have the program send a message, 
which is normally sent to the QSYSOPR queue, to another queue in place of or in 
addition to QSYSOPR. 


The following is an example of a user-defined program (again with only one 
procedure) to handle break messages. The display station user does not need to 
respond to the messages CPA5243 (Press Ready, Start, or Start-Stop on device &1) 
and CPA5316 (Verify alignment on device &3) when this program is used. 

BRKPGM: PGM (&MSGQ &MSGQLIB &MSGMRK) 


DCL &MSGQ TYPE(*CHAR) LEN(10) 
DCL &MSGQLIB TYPE(*CHAR) LEN(10) 
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DCL &MSGMRK TYPE(*CHAR) LEN(4) 

DCL &MSGID TYPE(*CHAR) LEN(7) 

RCVMSG MSGQ(&MSGQLIB/&MSGQ) MSGKEY(&MSGMRK) + 
MSGID(&MSGID) RMV(«*NO) 

/* Ignore message CPA5243 */ 

IF (&MSGID *EQ 'CPA5243') GOTO ENDBRKPGM 

/* Reply to forms alignment message */ 

IF (&MSGID *EQ 'CPA5316') + 
DO 
SNDRPY MSGKEY(&MSGMRK) MSGQ(&MSGQLIB/&MSGQ) RPY(I) 
ENDDO 

/* Other messages require user intervention */ 

ELSE CMD(DSPMSG MSGQ(&MSGQLIB/&MSGQ) ) 

ENDBRKPGM: ENDPGM 


Attention: 


In the above example of a break-handling program, if a CPA5316 message should 
arrive at the queue while the DSPMSG command is running, the DSPMSG display 
shows the original message that caused the break and the CPA5316 message. The 
DSPMSG display waits for the operator to reply to the CPA5316 message before 
proceeding. 


Note: This program cannot open a display file if the interrupted program is 
waiting for input data from the display. 


You can use the system reply list to indicate the system will issue a reply to 
predefined inquiry messages. The display station user, therefore, does not need to 
reply. For more information, see 


A procedure within a user break-handling program may need a Suspend and 

Restore procedure to ensure the display is suspended and restored while the 

message handling function is being performed. The Suspend and Restore 

procedure is necessary only if the following conditions exist: 

* A procedure in the break-program displays other menus or screens 

* The break-program calls other programs which may display other menus or 
screens. 


The following example clarifies the user procedure and display file needed to 
suspend and restore the display: 


Note: RSTDSP(*YES) must be specified to create the display file. 


A R SAVFMT OVERLAY KEEP 
Ax 

A R DUMMY OVERLAY 

A KEEP 

A ASSUME 

A DUMMYR 1A 1 2DSPATR(ND) 


PGM PARM(&MSGQ &MSGLIB &MRK) 
DCL VAR(&MSGQ) TYPE(*CHAR) LEN(10) 
DCL VAR(&MSGLIB) TYPE(*CHAR) LEN(10) 
DCL VAR(&MRK) TYPE(*DEC) LEN(4) 
DCLF FILE(UDDS/BRKPGMFM) 
SNDF RCDFMT (SAVFMT) 
CALL PGM(User's Break Program) 
SNDF RCDFMT(SAVFMT) 
ENDPGM 
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If you do not want the user specified break-handling program to interrupt the 
interactive job, the program may be submitted to run in batch. You may do this by 
specifying a break-handling program that receives the message and then performs 
a SBMJOB. The SBMJOB performs a call to the current break-handling program 
with any parameters that you want to use. (An example is information from the 
receive message.) Control will then be returned to the interactive job and it will 
continue normally. 


QSYSMSG Message Queue 


The QSYSMSG message queue is an optional queue that you can create in the 
QOSYS library. If it exists and is not damaged, certain messages are directed to it 
instead of, or in addition to, the QSYSOPR message queue. This allows a 
user-written program to gain control when certain messages are sent. You should 
not create the QSYSMSG queue unless you want it to receive specific messages. 


Enter the following command to create the QSYSMSG queue: 


CRTMSGQ QSYS/QSYSMSG + 
TEXT('Optional MSGQ to receive specific system messages') 


Once the QSYSMSG message queue is created, all of the specific messages (shown 
below in ag ) are directed to it. You can 
write a program to receive messages for which you can perform special action and 
send other messages to the QSYSOPR message queue or another message queue. 
This program should be written as a break-handling program. 


Messages Sent to QSYSMSG Message Queue 


This topic describes the specific messages sent to the QSYSMSG message queue. If 
the QSYSMSG message queue exists, the system sends the following messages to 
OSYSMSG instead of OQSYSOPR: 


° CPF1269, CPF1393, CPF1397 
* CPI2209, CPI9014, and messages CPI96C0 through CPI96C7 


The system sends all other messages in this topic to both QSYSMSG and 
QSYSOPR. 


CPD4070 
Negative response received for remote location &5, device 
description &4. 


CPF0907 
Serious storage condition may exist. Press HELP. 


This message is sent if the amount of available auxiliary storage in the 
system auxiliary storage pool has reached the threshold value. 


The system service tools function can be used to display and change the 
threshold value. For more information, see the PRENED OES hg 
book. 


CPF8AC4 
Reserved library name &7 in use. 


CPF9E7C 
Operating System/400 grace period expired. 
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The software license grace period for Operating System/400 has expired. 
Successful completion of the next initial program load (IPL) requires a 
software license key. 


Contact your IBM marketing representative or IBM business partner for a 
new Operating system/400 software license key. Use the Add License Key 
Information (ADDLICKEY) command to add the software license key. 


CPF1269 
Program start request received on communications device was rejected 
with reason codes. 


This message is sent when a start request is rejected and contains a reason 
code identifying why the rejection occurred. 


If a password is not valid or an unauthorized condition occurs using 
APPC, it may mean that a normal job is in error or that someone is 
attempting to break security. You may choose to prevent further use of the 
APPC device description until the condition is understood by doing the 
following: 

* Sending the message to the QSYSOPR message queue. 

* Recording the attempt for the security officer to review. 

* Issuing the End Mode (ENDMOD) command to set the allowed jobs to 
zero. This allows jobs that are currently using the peer device 
description to remain active, but prevents other jobs from starting until 
the condition is understood. 

* Counting the number of attempts in a given time period. You could 
establish a threshold in your program for the number of attempts that 
were not valid before you take serious action (such as changing the 
maximum number of sessions to zero). You may want to assign this 
threshold value by unit of work identifier (which may be blank), by 
APPC device description, or for your entire APPC environment. 


CPF1393 
User profile has been disabled because maximum number of sign-on 
attempts has been reached. 


This message is sent when a user has attempted to sign-on multiple times, 
causing the User Profile to be disabled. 


CPF1397 
Subsystem varied off work station. 


This message is sent if the threshold value assigned by the system value 
QMAXSIGN is reached and the device is varied off. The message indicates 
that a user is not entering a valid password. The message data for CPF1397 
contains the name of the device from which the message was sent. You can 
use this information and design a program to take appropriate action. You 
could consider performing one or several of the following: 

* Send the same message to the QSYSOPR message queue 

* Record the attempt for the security officer to review 


* Automatically vary on the device after a significant time delay 


CPF510E 
Network interface &9 failed while doing a read or write to device 
&4, 


The system has detected a network interface failure and is attempting error 
recovery for the network interface. 
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Try the request again. Recommendations on program recovery are in the 


e book. If the problem occurs again, 
enter the Analyze Pisblem (ANZPRB) command to run problem analysis. 


CPF5167 
SNA session for remote location &5, device description &4 ended 
abnormally. 


The Systems Network Architecture (SNA) session ended due to a request 
shutdown (RSHUTD), request recovery (ROR), unbind (UNBIND), or 
notify power off (NOTIFY) command received from the remote controller. 


Contact the remote controller operator to determine why the 
communications support ended the session. Correct the error, and try the 
request again. 


CPF5244 
Internal system failure for remote location &5, device description 
&4. 


Vary off the device. Vary the device on and try the request again. If the 
problem continues, report the problem (ANZPRB command). 


CPF5248 
SNA protocol violation for data received for remote location &5, 
device description &4. 


The Systems Network Architecture (SNA) request received for remote 
location &5, device description &4 violates SNA protocol. The system 
received a negative response with sense data &7 to the controller. 


Correct the problem in the controller program and try the request again. 
For more information on sense data and associated errors, see the Foon 


CPF5250 
Negative response with sense data &/ received for remote location 
&5. 


The system received a negative response with sense data &7 for remote 
location &5 device description &4. The first four characters of the data did 
not begin with 10xx, 08xx, or 0000. The Systems Network Architecture 
(SNA) session ended if it existed. 


Correct the error and try the request again. For more information on sense 
data and the causes of negative responses, see Systems Network Architecture 
Formats, GA27-3136. 


CPF5251 
Password or user ID not valid for request for remote location &5. 


A Systems Network Architecture (SNA) INIT-SELF command was received 
for finance remote location &5, device description &4 that did not contain 
valid authorization data. One of the following occurred: 


* The system could not find the user ID or password. 

* The system could not find the user ID. 

* The password was not valid for this user ID. 

* No authorization exists for this user ID to use device description &4. 
* The user profile was not accessible. 
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¢ The user ID contained a character that is not valid. 


Have the user try the request again with a valid user ID and password. If 
the user has no authorization to the device, use the Grant Object Authority 
(GRTOBJAUT) command to authorize the user to this device. 


CPF5257 
Failure for device or member 8&4 file &2 in library &3. 


An error occurred during a read or write operation. If this is a display file, 
the display may not be usable. 


See the previously listed messages, correct the errors, and try the request 
again. If the problem continues, report the problem (ANZPRB command). 


CPF5260 
Switched connection failed for device &4 in file &2 in &3. 


Close the file and then try the request again. 


CPF5274 
Error on device for remote location &5 file &2 in &3. 


The program attempted an input operation or an output operation to 
program device &4, remote location &5 that had a prior error. 


Vary off device associated with remote location &5 and then on again 
(VRYCFG or WRKCFGSTS command). Then try the request again. 


CPF5341 
SNA session not established for remote location &5, device 
description &4. 


The Systems Network Architecture (SNA) session could not be established. 
The Synchronous Data Link Control (SDLC) frame size is not compatible 
with the request/response unit (RU) size. This is either a configuration 
error, or the SDLC frame size has been negotiated to a smaller value by 
OS/400. This occured while the remote controller is using the Exchange 
Identification (XID) command. 


The MAXLENRU parameter of the device description contains the 
specification of the RU size for retail and finance devices. 


The MAXFRAME parameter of the line description contains the SDLC 
frame size specification. The MAXFRAME parameter of the controller 
description also contains the specification for retail and finance devices. 
Do one or more of the following and try the request again: 

* Verify that the frame size and the RU size values are compatible. 

* Increase the SDLC frame size, or decrease the RU size, if necessary. 


* Verify that this configuration is compatible with the remote controller 
configuration. 


* If you are making configuration changes, you must vary the 
configuration off and on before the changes will take effect. 


CPF5342 
Line &9 failed on device description &4, remote location &5. 


The system has detected line failure while processing input or output and 
is attempting error recovery for the line. 
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Try the request again. If the problem continues, start problem analysis 
(ANZPRB command). For more information on program recovery, see the 


CPF5344 
Error on controller &9, device description &4. 


The system has detected a controller failure and is attempting error 
recovery for the controller. 


Try the request again. If the problem continues, start problem analysis 
(ANZPRB command). 


CPF5346 
Error for remote location &5, device description &4. 


Close the file. Vary off the device (VRYCFG command). Look at any 
system operator messages in the job log to determine if any action is 
necessary before you vary on the device. Correct the error, and vary on the 
device (VRYCFG command). Then try the request again. If the problem 
continues, start problem analysis (ANZPRB command). 


CPF5355 
Not able to locate object &7 in &8 of type *&9. 


Object &7 type *&9 is either being used in another process, is not varied 
on, or has no sessions available for advanced program-to-program 
communications. 


Close file &2. Try the request again when object &7 is available or varied 
on. If the object that could not be allocated is for APPC, there were no 
sessions available to use. You can change the WAITFILE parameter to 
allow the system to wait longer for a session to become available. The 
mode can also be changed (MAXSSN parameter) to make more sessions 
available. The remote system may also have to configure again to accept a 
greater number of sessions. If configuration exists for sufficient sessions, 
use the CHGSSNMAX command to attempt to increase the current session 
limit. 

CPI091F 
PWRDWNSYS &1 command in progress. 


This message is sent in a secondary partition, when the primary partition 
ends abnormally. 


CPI0948 
Mirrored protection is suspended on disk unit &1; 


The system is not able to locate a storage unit. Data has not been lost. The 
following information indicates where the system located the storage unit 
before the storage unit was missing from the system configuration: 


¢ Disk serial number: &5 

* Disk type: &3 

¢ Disk model: &4 

* Device resource name: &26 


Do the following: 


1. Use the system Resource Configuration List display to see the storage 
unit that is identified as missing. 
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2. Ensure the proper installation of power cable connections on the 
storage unit. 


CPI0949 
Mirrored protection is suspended on disk unit &1; 


The mirrored protection for the disk is suspended. 


CPI0950 
Storage unit now available. 


A storage unit, which was missing from the configuration, is now 
available. Data has not been lost. 


CPI0953 
ASP storage threshold reached. 


This message is sent if the amount of available storage in the specified 
auxiliary storage pool (ASP) has reached the threshold value. The message 
data for CPI0953 contains the auxiliary storage capacity, the auxiliary 
storage used, the percentage of threshold, and the percentage of auxiliary 
storage available. You can use this information to take appropriate action. 


CPI0954 
ASP storage limit exceeded. 


This message is sent if all available storage in the specified ASP has been 
used. 


CPI0955 
System ASP unprotected storage limit exceeded. 


This message is sent if all available storage in the system ASP has been 
used. 


CPI0964 
Weak battery condition exists. 


This message is sent if the external uninterruptible power supply or 
internal battery indicates a weak battery condition. 


CPI0965 
Failure of battery power unit feature in system unit. 


This message is sent if there is a failure of the battery or the battery 
charger for the battery power unit feature in the system unit. 


CPI0966 
Failure of battery power unit feature in expansion unit. 


This message is sent if there is a failure of the battery or the battery 
charger for the battery power unit feature in the expansion unit. 


CPI0970 
Disk unit &l not operating 


Disk unit &1 has stopped operating. No data has been lost. The following 
information identifies the disk unit that is not operating: 

* Disk serial number: &3 

* Disk type: &5 

* Disk model: &6 

* Disk address: &4 

* IOP resource name: &26 
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¢ Device controller resource name: &27 
e Device resource name: &28 


Press F14 to run problem analysis. 


CPI0988 
Mirrored protection is resuming on disk unit &1; 


This message is sent if the mirroring synchronization of a disk unit has 
started and disk mirroring protection is being resumed. One of the steps 
the system performs before disk mirroring protection is resumed is to copy 
data from one disk unit to another so that the data on both disk units is 
the same. You may observe slow system performance during the time that 
the data is being copied. After the copy of the disk data is complete, 
message CPI0989 is sent to this message queue, and disk mirroring 
protection resumes. 


CPI0989 
Mirrored protection resumed on disk unit &1; 


This message is sent if the mirroring synchronization of a disk unit 
completed successfully. The system completed the copy of data from one 
disk unit to the other. Disk mirroring protection is resumed. 


CPI0998 
Error occurred on disk unit &1; 


This message is sent if errors were found on disk unit &1; The message 
does not include information about the failure to run problem analysis. 


CPI0999 
Storage directory threshold reached. 


The storage directory is nearing capacity. This is a potentially serious 
system condition. The system repeats this message until it receives an IPL. 


You must reduce the amount of storage that is used on the system. To 

reduce the amount of storage that is used, do the following: 

* Delete objects from the system that are not needed. 

* Save objects that are not needed online by specifying STG(*FREE) on the 
Save Object (SAVOBJ) command. 


CPI099C 
Critical storage lower limit reached. 


The amount of storage that is used in the system auxiliary storage pool has 
reached the critical lower limit value. The system will now take the action 
that is specified in the QSTGLOWACN system value: &5. The possible 
actions are: 


* *MSG — The system takes no further action. 


* *CRITMSG — The system sends message CPI099B to the user that is 
specified by the CRITMSGUSR service attribute. 


* *REGFAC — The system submits a job to run the exit programs that are 
registered for the QIBM_QWC_QSTGLOWACN exit point. 


* *ENDSYS — The system ends to the restricted state. 
* *PWRDWNSYS — The system powers down immediately and restarts. 


You can reduce use of storage through the following actions: 
* Delete any unused objects. 
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* Save objects by specifying STG(*FREE) 
* Save the old unused log versions of QHST and then delete them. 
* Print or delete spooled files on the system. 


Failure to reduce the storage usage may lead to a situation that requires 
initialization of auxiliary storage and loss of user data. Use the 
WRKSYSSTS command to monitor the amount of storage that is used. Use 
the PRTDSKINF command to print information about storage usage. The 
WRKSYSVAL command can be used to display and change the auxiliary 
storage lower limit value (QSTGLOWLMT) and action (QSTGLOWACN). 


CPI099D 
System starting in storage restricted state. 


The system is being started to the restricted state because the amount of 
storage available is below the auxiliary storage lower limit. Failure to 
reduce storage usage may lead to a situation that requires initialization of 
auxiliary storage and the loss of user data. The console is the only active 
device. 

You can reduce the use of storage through the following actions: 

* Delete any unused objects. 

* Save objects by specifying STG(*FREE). 

* Save the old unused log versions of QHST and then delete them. 

* Print or delete spooled files on the system. 


Failure to reduce the storage usage may lead to a situation that requires 
initialization of auxiliary storage and loss of user data. Use the 
WRKSYSSTS command to monitor the amount of storage that is used. Use 
the PRTDSKINF command to print information about storage usage. The 
WRKSYSVAL command can be used to display and change the auxiliary 
storage lower limit value (QSTGLOWLMT) and action (QSTGLOWACN). 


CPI099E 
Storage lower limit exit program error occurred. 


An error occurred while calling a user exit program for exit point 
QIBM_QWC_QSTGLOWACN. The reason code is &1. The reason codes 
and their meanings follow: 


An error occurred while running the user exit program. 
The system did not find a user exit program. 

The system did not find a registered user exit program. 
A user exit program did not complete in 30 minutes. 


The job running the user exit program ended. 


ou Ron > 


The system did not submit the user exit program job because the 
system is ending. 


7. The system did not submit the user exit program job because errors 
occurred. 


8. The system submitted the user exit program job, but issued warnings 
as well. 


9. The system could not retrieve registration information for the exit 
point. 


10. The system did not submit the user exit program job because the 
maximum number of failed exit program jobs was exceeded. 


252 OS/400 CL Programming V5R2 


11. An unexpected error occurred in the user exit program job. 


CPI099F 
PWRDWNSYS &1 command in progress. 


This message is sent in a secondary partition, when the primary partition 
powers down. 


CPI116A 
Mirrored protection suspended on the load source disk unit. 


Suspension of mirrored protection occurs on disk unit 1. Data has not been 
lost. Disk unit 1 is attached to the Multi-Function I/O Processor (MFIOP). 
Repair the disk unit as soon as possible. Do not power down the system, 
IPL the system, or perform any operation which would IPL the system 
until after completing disk repairs to unit 1. 

The following information identifies the unit that is suspended: 

* Disk serial number: &5 

* Disk type: &3 

* Disk model: &4 


« Device resource name: &26 


The system will automatically resume mirroring after corrections are made 
to the error. 


CPI116B 
Mirrored protection still suspended on the load source disk unit. 


Mirrored protection remains suspended on disk unit 1. Data has not been 
lost. Disk unit 1 is attached to the Multi-Function I/O Processor (MFIOP). 
Repair the disk unit as soon as possible. Do not power down the system, 
IPL the system, or perform any operation which would IPL the system 
until after repairing disk unit 1. 

The following information identifies the unit that is suspended: 

* Disk serial number: &5 

* Disk type: &3 

* Disk model: &4 

* Device resource name: &26 


See the previously listed messages in this message queue to determine the 
failure that caused suspension of mirrored protection. Perform the 
recommended recovery procedures. 


CPI116C 
Compressed disk unit &1 is full. 


Compressed disk unit &1 is temporarily full. The storage subsystem 
controller has detected the condition and is repositioning the data on the 
compressed disk unit. The system does this to maximize the amount of 
storable data on the disk unit. This operation could take a number of 
minutes to complete. When the storage subsystem controller has completed 
the repositioning of the data, the system will resume normal operations. 


The following information identifies the unit that is full: 
* Disk serial number: &5 

* Disk type: &3 

* Disk model: &4 
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e Device resource name: &26 


Wait for the storage subsystem controller to reposition the data on the 
compressed disk unit. Do not power off the system. If you are frequently 
receiving this message that indicates that a compressed disk unit is full, do 
one or more of the following: 


1. Save objects that are not needed from the auxiliary storage pool by 
specifying STG(*FREE) on the Save Object (GAVOBJ) command. 


2. Delete objects that are not needed from the auxiliary storage pool. 


3. Move one or more folders to a different auxiliary storage pool by 
saving the folder, deleting the folder, and restoring the folder to a 
different auxiliary storage pool. 

4. Increase the storage capacity by adding disk units to the auxiliary 
storage pool. You can direct the system to immediately overflow data 
from the user auxiliary storage pool into the system auxiliary storage 
pool. This prevents you from having to wait for the storage subsystem 
controller to reposition the data on the compressed disk unit each time 
it becomes full. Use the Change ASP Attribute (CHGASPA) command 
to change the compression recovery policy to immediately overflow 
data to the system auxiliary storage pool whenever a compressed disk 
unit becomes full. 


CPI1117 
Damaged job schedule &1 in library &2 deleted. 


This message is sent when the job schedule in the library was deleted 
because of damage. 


CPI1136 
Mirrored protection still suspended. 


This message is sent each hour if mirrored protection is still suspended on 
one or more disk units. 


CPI1138 
Storage overflow recovered. 


This message is sent when ASP &1 no longer has any objects that have 
overflowed into the system ASP for reason &2; 


CPI1139 
Storage overflow recovery failed. 


This message is sent when an attempt to recover from storage overflow 
failed. 


CPI1153 
System password bypass period ended. 


This message is sent when the system has been operating with the system 
password bypass period in effect. The bypass period has ended. Unless the 
correct system password is provided, the next IPL will not be allowed to 
complete successfully. 


CPI1154 
System password bypass period will end in &5 days. 


This message is sent when the system password (during a previous IPL) 
was either not entered or not entered correctly, and the system bypass 
period was selected. 
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CPI1159 
System ID will expire with &1 more installs. 


This message is sent when the system ID is about to expire. The IBM 
Service Representative should be contacted. 


CPI1160 
System ID has expired. 


This message is sent when the system identifier has expired. The IBM 
Service Representative should be contacted. 


CPI1161 
Unit &l with device parity protection not fully operational. 


Unit &1 is part of a disk unit subsystem with device parity protection. Unit 
&1 requires service. The data has been saved. Reduced performance, 
machine checks, and possible data loss can occur if this condition is not 
corrected. 


CPI1162 
Unit &l with device parity protection not fully operational. 


Unit &1 is part of a disk unit subsystem with device parity protection. Unit 

&1 is not fully operational for one of the following reasons: 

* The service representative is repairing the unit. 

* The unit is not operating, but there is not enough information to run 
problem analysis. 


CPI1165 
One or more device parity protected units still not fully 
operational. 


One or more units within disk unit subsystems with device parity 
protection are still not fully operational due to errors. 


CPI1166 
Units with device parity protection fully operational. operational. 


Units for all IOP subsystems that provide device parity protection are fully 
operational. 


CPI1167 
Temporary I/@ processor error occurred. 


An error condition occurred on a I/O processor with disk devices. 


CPI1168 
Error occurred on disk unit &1; 


Disk unit number &1 found an error. A damaged object can occur. A 
machine check can occur if the problem becomes worse. The following 
identifies the disk unit. 


CPI1169 
Disk unit &l not operating. 


Disk unit &1 has stopped operating. No data has been lost. 


CPI1171 
Internal system object cannot be recovered. 


The internal system object that contains an index of jobs on the system was 
damaged. The system could not recover the object after &1 attempts. 
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No recovery action is necessary, but the performance of searching for jobs 
may be affected. 


CPI1468 
System work control block table nearing capacity. 


The system sends this message when the number of entries in the system 
job tables approaches the maximum number allowed. Permitting the job 
tables to fill completely may prevent the successful submission of jobs or 
the completion of the subsequent IPL. 


CPI22AA 
Unable to write audit record to QAUDJRN. 


An unexpected &1 exception occurred at instruction &2 of program 
QSYSAUDR when attempting to write an audit record of type &3 to the 
QAUDJRN audit journal. The action specified by the Auditing End Action 
(QAUDENDACN) system value will be performed. 


CPI2209 
User profile &1 deleted because it was damaged. 


This message is sent when a user profile is deleted because it was 
damaged. This user profile may have owned objects prior to being deleted. 
These objects now have no owner. A Reclaim Storage (RCLSTG) command 
can be used to transfer the ownership of these objects to the QODFTOWN 
user profile. 


CPI2239 
QAUDCTL system value changed to &l. 


During the install, QAUDCTL was changed to *NONE because the security 
auditing function was not available. The security auditing function is now 
available so the QAUDCTL system value has been changed to its original 
value. 


CPI12283 
QAUDCTL system value changed to «NONE. 


This message is sent each hour after auditing has been turned off by the 
system because auditing failed. To turn auditing back on or to determine 
why auditing failed, you can change system value QAUDCTL to a value 
other than *NONE. 


CPI2284 
QAUDCTL system value changed to «NONE. 


This message is sent during IPL if auditing was turned off by the system 
because auditing failed. To turn auditing back on or to determine why 
auditing failed, you can change system value QAUDCTL to a value other 
than *NONE. 


CPI8A13 
QDOC library nearing save history limit. 


This message is sent when the number of objects in library QDOC is 
approaching the limit for the number of objects that the system supports 
storing in one library. 


CPI8A14 
QDOC library has exceeded save history limit. 
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This message is sent when the number of objects in Library QDOC has 
exceeded the limit for the number of objects that the system supports in 
one library. 


CPI8898 
Optical signal loss is detected on optical bus. 


This message is sent when an optical bus failure is detected. The bus is 
running at reduced mode. This message is logged in the service activity 
log and have the PAR option available. 


CPI9014 
Password received from device not valid. 


This message is sent when a password has been received on a document 
interchange session that is not correct. It may indicate unauthorized 
attempts to access the system. 


CPI9476 
Temporary Device Error. 


An error condition occurred on addressed disk unit &28. However, the 
error condition has recovered. Unit &28 is still operable. 


Press F14 to run problem analysis. 


CPI9490 
Disk error on device &25; 


This message is sent when a disk error has been detected. 


CPI94A0 
Disk error on device &25; 


This message is sent when a disk error has been detected. 


CPI94CE 
Error detected in bus expansion adapter, bus extension adapter, 
System Processor, or cables. 


This message is sent when the system has detected a failure in the main 
storage. System performance may be degraded. Run problem analysis to 
determine the failing card. 


CPI94CF 
Main storage card failure is detected. 


This message is sent when the system has detected a failure in the main 
storage. System performance may be degraded. Run problem analysis to 
determine the failing card. 


CPI94FC 
Disk error on device &25; 


This message is sent when the 9336 Disk Unit has determined that one of 
its parts is exceeding the error threshold and is starting to fail. 


CPI96C0 
Protected password could not be validated. 


The system sends this message when the protected password received for 
the user profile by the APPC sign-on transaction program was not correct. 
This message contains a reason code that identifies the error. Check the 
reason code to take appropriate action. 
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CPI96C1 
Sign-on request GDS variable was not correct. 


The system sends this message when the sign-on request GDS variable 
received by the APPC sign-on transaction program was not correct. Remote 
program have to sent the correct sign-on data. 


CPI96C2 
User password could not be changed. 


This messages is sent if a security problem has occured. 


CPI96C3 
Message &4 returned on system call. 


The system sends this message when a message returns on a system call 
by the APPC sign-on transaction program. 


CPI96C4 
Password not correct for user profile. 


The system sends this message when the password specified is not correct. 


CPI96C5 
User &4 does not exist. 


The system sends this message when the received user does not exist on 
the system. 


CPI96C6 
Return code &4 received on call to CPI-Communications. 


The system sends this message when a call to CPI-Communications has 
sent a return code. Refer to the Common Programming Interface 
Communications Reference manual to see the return code description and 
determine why it is failing. 


CPI96C7 
System failure in the APPC sign-on transaction program. 


The system sends this message when receiving an unexpected error. Run 
problem analysis to determine the failing. 


CPPODD9 
A system processor failure is detected. 


This message is sent when a system processor or system processor cache 
has failed. System performance may be degraded. 


CPPODDA 
A system processor failure is detected in slot 9. 


This message is sent when a system processor or system processor cache 
has failed. System performance may be degraded. 


CPPODDB 
A system processor failure is detected in slot 10. 


This message is sent when a system processor or system processor cache 
has failed. System performance may be degraded. 


CPPODDC 
A system processor failure is detected. 


This message is sent when the system has detected an error on the system 
processor. System performance may be degraded. 
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CPPODDD 
System processor diagnostic code detected an error. 


This message is sent when a failure has been detected by the 
system-processor diagnostics during IPL, but the system is still able to 
function. 


CPPODDE 
A system processor error is detected. 


This message is sent when a control failure is detected on a system 
processor. Hardware ECC is correcting the failure. However, if you 
performed an initial program load (IPL), control could not be initialized 
and the system would reconfigure itself without that processor. 


CPPODDF 
A system processor is missing. 


This message is sent when a processor is missing on a multi-processor 
system. 


CPP29B0 
Recovery threshold exceeded on device &25; 


This message is sent when one of the parts in the 9337 disk unit is starting 
to fail. 


CPP29B8 
Device parity protection suspended on device &25; 


This message is sent when one of the parts in the 9337 disk array is failing. 
Protection for implementation of RAID 5 technique has been suspended on 
the disk array. 


CPP29B9 
Power protection suspended on device &25; 


This message is sent when one of the power modules in the 9337 disk 
array is failing. Power protection has been suspended on the disk array. 


CPP29BA 
Hardware error on device &25; 


This message is sent when one of the parts in the 9337 disk array has 
failed. Service action is required. 


CPP951B 
Battery power unit fault. 


This message is sent when the battery power unit has failed. 


CPP9522 
Battery power unit fault. 


This message is sent when the battery power unit in the 5042 Expansion 
Unit or 5040 Extension Unit has failed. 


CPP955E 
Battery power unit not installed. 


This message is sent when the battery power unit in the 9406 System Unit 
power supply is not installed. 


CPP9575 
Battery power unit in 9406 needs to be replaced. 
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This message is sent when the battery power unit in the 9406 System Unit 
has failed and needs to be replaced. It may still work, but more than the 
recommended number of charge-discharge cycles have occurred. 


CPP9576 
Battery power unit in 9406 needs to be replaced. 


This message is sent when the battery power unit in the 9406 System Unit 
has failed and needs to be replaced. It may still work, but it has been 
installed longer than recommended. 


CPP9589 
Test of battery power unit complete. 


This message is sent when testing has been completed for the battery 
power unit, and the results have been logged. 


CPP9616 
Battery power unit not installed. 


This message is sent when the battery power unit has not been installed in 
the 5042 Expansion Unit or 5040 Extension Unit power supply. 


CPP9617 
Battery power unit needs to be replaced. 


This message is sent when the battery power unit in the 5042 Expansion 
Unit or 5040 Extension Unit needs to be replaced. It may still work, but 
more than the recommended number of charge-discharge cycles have 
occurred. 


CPP9618 
Battery power unit needs to be replaced. 


This message is sent when the battery power unit in the 5042 Expansion 
Unit or 5040 Extension Unit needs to be replaced. It may still work, but it 
has been installed longer than recommended. 


CPP961F 
DC Bulk Module 3 fault. 


This message is sent when the dc bulk module 3 of the 9406 System Unit 
has failed. 


CPP9620 
DC Bulk Module 2 fault. 


This message is sent when the dc bulk module 2 of the 9406 System Unit 
has failed. 


CPP9621 
DC Bulk Module 1 fault. 


This message is sent when the dc bulk module 1 of the 9406 System Unit 
has failed. 


CPP9622 
DC Bulk Module 1 fault. 


This message is sent when the dc bulk module 1 of the 5042 Expansion 
Unit or 5040 Extension Unit has failed. Other dc bulk modules can also 
cause this fault. 


CPP9623 
DC Bulk Module 2 fault. 
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Sample Program to Receive Messages from QSYSMSG 


This message is sent when the dc bulk module 2 of the 5042 Expansion 


Unit or 5040 Extension Unit has failed. Other DC bulk modules can also 
cause this fault. 


CPP962B 
DC Bulk Module 3 fault. 


This message is sent when the dc bulk module 3 of the 5042 Expansion 
Unit or 5040 Extension Unit has failed. Other dc bulk modules can also 


cause this fault. 


The following is a sample program which receives messages from the QSYSMSG 


message queue. The program consists of a single procedure which is receiving 
messages and handling message CPF1269. The reason code in the CPF1269 
message is in binary format. This must be converted to a decimal value for the 


comparisons to the 704 and 705 reason codes. The procedure issues the ENDMOD 
command to prevent new jobs from being started until the situation is understood. 
It then sends the same message to a user-defined message queue to be reviewed by 
the security officer. It also sends a message to the system operator informing him 


of what occurred. If a different message is received, it is sent to the system 


operator. 


A separate job would be started to call this sample program. The job would remain 
active, waiting for a message to arrive. The job could be ended using the ENDJOB 


command. 

[BRK R KER AKER AKER AKER IKEA KEIR KER KK AAR KKK KKK AKER KKE AK KEK AKER | 
/* x/ 
/* Sample program to receive messages from QSYSMSG */ 
/* x/ 
[BRK K KEK AKER AKER AKER IKEA KEIRA KK AKKEAK KKK A KKK A IKEA AKER AREA A KEKE | 
/* */ 
/* Program looks for message CPF1269 with a reason code of 704 */ 
/* or 705. If found then notify QSECOFR of the security failure. */ 
/* Otherwise resend the message to QSYSOPR. */ 
/* x/ 
/* The following describes message CPF1269 */ 
/* */ 
/* CPF1269: Program start request received on communications */ 
/* device &1 was rejected with reason codes &6,; &7; */ 
/* */ 
/* Message data from DSPMSGD CPF1269 x/ 
/* */ 
/* Data type offset length Description x/ 
/* x/ 
/* &1  *CHAR 1 10 Device x*/ 
/* &2 CHAR 11 8 Mode x/ 
/* &3 «CHAR 19 10 Job - number */ 
/* &4 CHAR 29 10 Job - user x/ 
/* &5 «CHAR 39 6 Job - name x/ 
/* &6 = «BIN 45 2 Reason code - major x/ 
/* &7  ~=*BIN 47 2 Reason code - minor */ 
/* &8&  ¥*CHAR 49 8 Remote location name */ 
/* &9 «CHAR 57 *VARY Unit of work identifier x/ 
/* */ 


[RRR KER AKER A KKK KER KKK KKK EA KKK KK IKKE AK KEK AKER ERK KE | 


PGM 


DCL 
DCL 
DCL 


&MSGID 
&MSGDTA 


&MSG 


*CHAR LEN( 7) 
*CHAR LEN(100) 
*CHAR LEN(132) 
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LOOP: 


PROBLEM: 
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DCL &DEVICE *CHAR LEN( 10) 
DCL &MODE *CHAR LEN( 8) 
DCL &RMTLOC *CHAR LEN( 8) 


MONMSG CPFOOOO EXEC(GOTO PROBLEM) 


[BERR KERR KER AK REIKI KKK AK KAKA KEKE K ERIK EAR ERE | 
/* Fetch messages from QSYSMSG message queue x*/ 
[RRR RK RRR KKK A KK A KKK K KKK KKK KAKI KKK AK KKK AKER KEKE KEAKKE KK | 


RCVMSG MSGQ(QSYS/QSYSMSG) WAIT(*MAX) MSGID(&MSGID) + 
MSG(&MSG) MSGDTA(&MSGDTA) 


IF ((&MSGID *EQ 'CPF1269') /* Start failed msg */ + 
*AND ((%BIN(&MSGDTA 45 2) *EQ 704) Bs 
«OR (SBIN(&MSGDTA 45 2) *EQ 705)) ) + 
THEN (DO) 
[RRR KKK A KKK K KK ERK KKK AKER KK KKK KKK AK KEK KK EAR KEK AKER AKER EK | 
/* Report security failure to QSECOFR */ 


[BRK A KKK AK KEK KEIR K ERIKA KKK KK KA KKK KK EA KEK AKER A KERR | 


CHGVAR &DEVICE %SST(&MSGDTA 1 10) /* Extract device */ 
CHGVAR &MODE %SST(&MSGDTA 11 8) /* Extract mode */ 
CHGVAR &RMTLOC %SST(&MSGDTA 49 8) /* Get loc name +*/ 


ENDMOD RMTLOCNAME(&RMTLOC) MODE (&MODE) 


SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGDTA(&MSGDTA) + 
TOMSGQ(QSECOFR) 


SNDPGMMSG MSG('Device ' *CAT &DEVICE *TCAT ' Mode ' + 
*CAT &MODE *TCAT ' had security failure, + 


session max changed to zero') + 
TOMSGQ(QSYSOPR) 
ENDDO 
ELSE DO 
[RRA KKK IKK EK KK ERK KER AKER KK KKK KKK KKK KEIR KE AK KEK KER KK | 
/* Other message - Resend to QSYSOPR */ 


[BRK R KKK IKK EK KEIR KER AKER AKER KKK AK KEK KK EAR EKER AKER | 


SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGDTA(&MSGDTA) + 


TOMSGQ(QSYSOPR) 
/* SNDPGMMSG would fail if the message does x/ 
/* not have a MSGID or is not in QCPFMSG */ 


MONMSG MSGID(CPFQ000) + 
EXEC(SNDPGMMSG MSG(&MSG) TOMSGQ(QSYSOPR) ) 
ENDDO 


GOTO LOOP /* Go fetch next message */ 


[RRR RK RRR KER AK KR AK KKK KK KKK AK KKK KEKE KKK KKK AKER AKER | 


/* Notify QSYSOPR of abnormal end */ 


[BRK RK RIKER AK KEI K ERIK KAKA KKK KEKE AKER AKER AKERAKEE KK | 


SNDPGMMSG MSG('QSYSMSG job has abnormally ended') + 
TOMSGQ(QSYSOPR) 
MONMSG CPFO000 


SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) + 
MSGDTA('Unexpected error occurred') 
MONMSG CPFO000 


ENDPGM 


Using the System Reply List 


The system reply list allows you to specify that the system issue the reply to 
specified predefined inquiry messages so the display station user does not need to 
reply. Only inquiry messages can be automatically responded to. 


The system reply list contains message identifiers, optional compare data, a reply 
value for each message, and a dump attribute. The system reply list applies only to 
predefined inquiry messages that are sent by a job that uses the system reply list. 
You specify that a job is to use the system reply list for inquiry messages on the 
INQMSGRPY(*SYSRPYL) parameter on the following commands: 

* Batch Job (BCHJOB) 

* Submit Job (SBMJOB) 

* Change Job (CHGJOB) 

* Create Job Description (CRTJOBD) 

* Change Job Description (CHGJOBD) 


When a predefined inquiry message is sent by a job that uses the system reply list, 
the system searches the reply list in ascending sequence number order for an entry 
that matches the message identifier and, optionally, the compare data of the reply 
message. If an entry is found, the reply specified is issued and the user is not 
required to enter a reply. If an entry is not found, the message is sent to the 
display station user for interactive jobs or system operator for batch jobs. 


The system reply list is shipped with the system with the following initial entries 


defined: 
Sequence Message 
Number Identifier Compare Value | Reply Dump 
10 CPA0700 *NONE D *YES 
20 RPGOO0O *NONE D *YES 
30 CBE0000 *NONE D *YES 
40 PLIO000 *NONE D *YES 


These entries indicate that a reply of D is to be sent and a job dump is to be taken 
if the message CPA0700-CPA0799, RPG0000-RPG9999, CBE0000-CBE9999, or 
PLI0000-PLI9999 (which indicate a program failure) is sent by a job using the 
system reply list. For the system to use these entries, you must specify that the jobs 
are to use the system reply list. 


To add other inquiry messages to the system reply list, use the Add Reply List 
Entry (ADDRPYLE) command. On this command you can specify the sequence 
number, the message identifier, optional compare data, compare data CCSID, reply 
action, and the dump attribute. The ADDRPYLE command function can be easily 
accessed by using the Work with System Reply List Entries (WRKRPYLE) 
command. 


The following reply actions can be specified for the inquiry messages that are 

placed on the system reply list (the parameter value is given in parentheses): 

* Send the default reply for the inquiry messages (*DFT). In this case, the default 
reply for the message is sent. The message is not displayed, and no default 
handling program is called. 
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Require the work station user or system operator to respond to the message 
(*RQD). If the message queue to which the message is sent (work station 
message queue for interactive jobs and QSYSOPR for batch jobs) is in break 
mode, the message is displayed, and the work station user must respond to the 
message. This option operates as if the system reply list were not being used. 


Send the reply specified in the system reply list entry (message reply, 32 
characters maximum). In this case, the specified reply is sent as the response to 
the message. The message is not displayed, and no default handling program is 
called. 


The following commands add entries to the system reply list for messages 
RPG1241, RPG1200, CPA4002, CPA5316, and any other inquiry messages: 


ADDRPYLE SEQNBR(15) MSGID(RPG1241) RPY(C) 

ADDRPYLE SEQNBR(18) MSGID(RPG1200) RPY(*DFT) DUMP(*YES) 

ADDRPYLE SEQNBR(22) MSGID(CPA4002) RPY(*RQD) + CMPDTA('QSYSPRT') 
ADDRPYLE SEQNBR(25) MSGID(CPA4002) RPY(G) 


ADDRPYLE SEQNBR(27) MSGID(CPA5316) RPY(I) DUMP(*NO) + 
CMPDTA('QSYSPRT' 21) 


ADDRPYLE SEQNBR(9999) MSGID(*ANY) RPY(*DFT) 


The system reply list now appears as follows: 


Compare 

Sequence Message Value (b is a | Compare 

Number Identifier blank) Start Position | Reply Dump 
10 CPA0700 1 D *YES 
15 RPG1241 1 C *NO 
18 RPG1200 1 *DFT *YES 
20 RPGO000 1 D *YES 
22 CPA4002 "QSYSPRT' 1 *ROD *NO 
25 CPA4002 1 G *NO 
27 CPA5316 "QSYSPRT' 21 I *NO 
30 CBE0000 1 D *YES 
40 PLI0000 1 D *YES 
9999 *ANY 1 *DFT *NO 


For a job that uses this system reply list, the following occurs when the messages 
that were added to the reply list are sent by the job: 


For sequence number 15, whenever an RPG1241 message is sent by a job that 
uses the system reply list, a reply of C is sent and the job is not dumped. 


For sequence number 18, a generic message identifier is used so whenever an 
RPG1200 inquiry message is sent by the job, the default reply is sent. The 
default reply can be the default reply specified in the message description or the 
system default reply. Before the default reply is sent, the job is dumped. The 
previous entry that was added overrides this entry for message RPG1241. 

For sequence number 22, if the inquiry message CPA4002 is sent with the 
compare data of QSYSPRI, the message is sent to the display station user, and 
the user must issue the reply. 
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When a compare value is specified without a start position, the compare value is 
compared to the message data beginning in position 1 of the substitution data in 
the message. 


Sequence number 22 tests for a printer device name of QSYSPRT. For an 
example of testing one substitution variable with a different start position, see 
sequence number 27. 


* For sequence number 25, if the inquiry message CPA4002 (verify alignment on 
printer &1;) is sent with the compare not equal to QSYSPRT, a reply of G is sent. 
The job is not dumped. Sequence number 22 requires an operator response to 
the forms alignment message if the printer device is QSYSPRT. Sequence number 
25 defines that if the forms alignment inquiry message occurs for any other 
device, to assume a default response of G=Go. 


* For sequence number 27, if the inquiry message CPA5316 is sent with the 
compare data of TESTEDFILETSTLIBRARYQSYSPRT, a reply of I is sent. 


When a compare value and a start position are specified, the compare value is 
compared with the message data beginning with the start position. In this case, 
position 21 is the beginning of the third substitution variable. For message 
CPA5316, the first four substitution variables are as follows: 


&l1 ODP file name *CHAR 10 
&2 ODP library name *CHAR 10 
&3 ODP device name *CHAR 10 
&4 Line number for first line *BIN 2 


Therefore, sequence number 27 tests for an ODP device name of QSYSPRT 
before sending a reply. 


* For sequence number 9999, the message identifier of *ANY applies to any 
predefined inquiry message that is not matched by an entry with a lower 
sequence number, and the default reply for these inquiry messages is sent. If this 
entry were not included in the system reply list, the display station user would 
have to respond to all other inquiry messages that were not included in the 
system reply list. 


When the compare value contains *CCHAR data, the message data that is from the 
sending function is converted to the CCSID of the message data that is stored in 
the system reply list before the compare is made. The system converts only data 
that is of type *CCHAR. IBM provides online information about the Add Message 
Description (ADDMSGD) command *CCHAR data. Refer to the CL section of the 
Programming category in the iSeries Information Center. 


CAUTION: 
The following restrictions apply when using *CCHAR data as compare data: 


* You cannot mix *CCHAR data with other data when adding this type of reply 
list entry. 
* You cannot include the length of the *CCHAR data in the compare data. 


If you mix *CCHAR data or include the length of the *CCHAR data, 
unpredictable results may occur. 


An entry remains on the system reply list until you use the Remove Reply List 
Entry (RMVRPYLE) command to remove it. You can use the Change Reply List 
Entry (CHGRPYLE) command to change the attributes of a reply list entry, and 
you can use the Work with System Reply List Entry (WRKRPYLE) command to 
display the reply entries currently in the reply list. 
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The job log receives a completion message indicating a successful change when the 
system reply list is updated using (ADDRPYLE), (CHGRPYLE), or (RMVRPYLE). 
The history log QHST also receives a completion message to record the change. 


Message Logging 


The two types of logs for messages are: 
* Job log 
* History log 


A job log contains information related to requests entered for a job. The QHST log 
contains system data, such as a history of job start and end activity on your 
system. 


Job Log 


Each job has an associated job log that can contain the following for the job: 
* The commands in the job. 


* The commands in a CL program if the CL program was created with the 
LOG(*YES) option or with the LOG(*JOB) option and a Change Job (CHGJOB) 
command was run with the LOGCLPGM(*YES) option (for more information on 


logging CL program commands, see 
= = 53). 


* All messages and message help sent to the requester and not removed from the 
call message queues. 


After the job ends, the job log can be written to either the output file QPJOBLOG 
or a database file. From the output file QPJOBLOG, the job log can be printed; 
from a database file, job log information can be queried using a database feature. 
You can also specify to not write job logs for jobs that have run successfully—a 
discussion about preventing job logs is presented later in this chapter. 


IBM provides online information about how to write a job log to a database file 
that requires the use of the QMHCTLJL API. Refer to the CL section of the 
Programming category of the iSeries Information Center. When directing the job 
log to the database file, the system can generate one or two files. The primary file 
contains the essential information of a message such as message ID, message 
severity, message type, and message data. The secondary file contains the print 
images of the message text. Parameters on the QMHCTLJL API control the optional 
production of the secondary file. You can use database and query features on the 


secondary files. 


for information on the formats of the primary and 


You can control what information the system writes in the job log. To do this, you 
specify the LOG parameter on the Create Job Description (CRIJOBD) command. 
You can change these levels by using the Change Job (CHGJOB) command or the 
Change Job Description (CHGJOBD) command. Three values make up the LOG 
parameter: Message level, message severity, and message text level. For more 
information on these commands, see the CL section of the Programming category 
of the iSeries Information Center. 


The first value, message level, has the following levels: 


Level Description 
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0 No data is logged. 


1 The only information to be logged is all messages sent to the job’s external 
message queue with a severity greater than or equal to the message 
severity specified. Messages of this type indicate when the job started, 
when it ended, and its status at completion. 


2 The following information is logged: 
* Level 1 logging information. 


* Any requests that result in high-level messages with a severity greater 
than or equal to the severity specified. If the request is logged, all of its 
associated messages are also logged. 


3 The following information is logged: 
* Logging level 1 and 2 information. 
° All requests. 
* Commands run by a CL program if allowed by the Log CL program 
commands job attribute and the Log attribute of the CL program. 
4 The following information is logged: 


* All requests and all messages with a severity code greater than or equal 
to the severity specified, including trace messages. 


* Commands run by a CL program if allowed by the Log CL program 
commands job attribute and the Log attribute of the CL program. 


Note: A high-level message is one that is sent to the program message 
queue of the program that receives the request. For example, 
QCMD is an IBM-supplied request processing program that 
receives requests. 


The second value, message severity, specifies the severity level in conjunction with 
the log level that causes error messages to be logged in the job log. Values 0 
through 99 are allowed. 


The third value in the LOG parameter, message text level, specifies the level of 
message text that is written in the job log. The values are: 


*SAME 
The current value for the message text level does not change. 


*MSG Only message text is written to the job log (message help is not included). 


*SECLVL 
The message and the message help (cause and recovery) are written to the 
job log. 


Before each new request is received by a request processing program, message 
filtering occurs. Message filtering is the process of removing messages from the 
job log based on the message logging level set for the job. 


Filtering does not occur after every CL command is called within a program. 
Therefore, if a CL program is run interactively or submitted to batch, the filtering 
runs once after the program ends because the program is not a request processor. 


Note: Since *NOLIST specifies that no job log is spooled for jobs that end 


normally, it is a waste of system resource in batch jobs to remove the 
messages from this log by specifying log level 0. 
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The following example shows how the logging level affects the information that is 
stored in the job message queue and, therefore, written to the job log, if one is 
requested. The example also shows that when the command is run interactively, 
filtering occurs after each command. 


Note: Both high-level and detailed message logging levels are included in the 
examples. High-level messages are identified as Message; detailed messages 
are identified as Detailed Message. 

1. The CHGJOB command specifies a logging level of 2 and a message severity of 

50, and that only messages are to be written to the job log (*MSG). 


Command Entry SYSTEM1 
Request level: 1 


Previous commands and messages: 
> CHGJOB LOG(2 50 *MSG) 


2. PGMA sends three informational messages with severity codes of 20, 50, and 60 
to its own call message queue and to the call message queue of the program 
called before the specified call (*PRV). The messages that PGMA sends to its 
own call message queue are called detailed messages. Detailed messages are 
those messages that are sent to the call message queue of the lower-level 
program call. 

PGMB sends two informational messages with severity codes of 40 and 50 to 
its own call message queue. These are detailed messages. PGMB also sends one 
informational message with a severity code of 10 to *PRV. 


Note that the CHGJOB command no longer appears on the display. According 
to logging level 2, only requests for which a message has been issued with a 
severity equal to or greater than that specified are saved for the job log, and no 
messages were issued for this request. If such a message had been issued, any 
detailed messages that had been issued would be saved for the job log and 
could be displayed by pressing F10. 


Command Entry SYSTEM1 - 
Request level: 1 
Previous commands and messages: 
> CALL PGMA 
Message sev 20 - PGMA 
Message sev 50 - PGMA 
Message sev 60 - PGMA 
> CALL PGMB 
Message sev 10 - PGMB 
Bottom 
Type command, press Enter. 
===> 
F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages 
Fll=Display full F12=Cancel F13=Information Assistant F24=More keys 
S 


3. When F10=Include detailed messages is pressed from the Command Entry 
display, all the messages associated with the request are displayed. Press F10 
again to exclude detailed messages. 
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Command Entry SYSTEM1 
Request level: 1 
All previous commands and messages: 
> CALL PGMA 
Detailed message sev 20 - PGMA 
Detailed message sev 50 - PGMA 
Detailed message sev 60 - PGMA 
Message sev 20 - PGMA 
Message sev 50 - PGMA 
Message sev 60 - PGMA 
> CALL PGMB 
Detailed message sev 40 - PGMB 
Detailed message sev 50 - PGMB 
Message sev 10 - PGMB 


Bottom 
Type command, press Enter. 
if 
F3=Exit F4=Prompt F9=Retrieve F10=Exclude detailed messages 
Fll=Display full F12=Cancel F13=Information Assistant F24=More Keys 
3 | 


4. When another command is entered (in this example, CHGJOB), the CALL PGMB 
command and all messages (including detailed messages) are removed. They 
are removed because the severity code for the high-level message associated 
with this request was not equal to or greater than the severity code specified in 
the CHGJOB command. The CALL PGMA command and its associated messages 
remain because at least one of the high-level messages issued for that request 
has a severity code equal to or greater than that specified. 


On the following display, the CHGJOB command specifies a logging level of 3, 
a message severity of 40, and that both the first- and second-level text of a 
message are to be written to the job log. When another command is entered, 
the CHGJOB command remains on the display because logging level 3 logs all 
requests. 


PGMC sends two messages with severity codes of 30 and 40 to the call 
message queue of the program called before the specified call (*PRV). 


PGMD sends a message with a severity of 10 to *PRV. 
( = 


Command Entry SYSTEM1 
Request level: 1 


Previous commands and messages: 
> CALL PGMA 
Message sev 20 - PGMA 
Message sev 50 - PGMA 
Message sev 60 - PGMA 
> CHGJOB LOG(3 40 *SECLVL) 
> CALL PGMC 
Message sev 30 - PGMC 
Message sev 40 - PGMC 
> CALL PGMD 
Message sev 10 - PGMD 


Bottom 
Type command, press Enter. 
Tt 
F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages 
Fll=Display full F12=Cancel F13=Information Assistant F24=More Keys 
ss S| 
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5. When another command is entered after the CALL PGMD command was entered, 
the CALL PGMD command remains on the display, but its associated message is 
deleted. The message is deleted because its severity code is not equal to or 
greater than the severity code specified on the LOG parameter of the CHGJOB 
command. 


The command SIGNOFF *LIST is entered to print the job log. 


Command Entry SYSTEM1 > 
Request level: 1 
Previous commands and messages: 
> CHGJOB LOG(3 40 *SECLVL) 
> CALL PGMC 
Message sev 30 - PGMC 
Message sev 40 - PGMC 
> CALL PGMD 
> CALL PGME 
Bottom 
Type command, press Enter. 
===> SIGNOFF *LIST 
F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages 
Fll=Display full F12=Cancel F13=Information assistant F24=More Keys 
oy 


The job log, which follows, contains all the requests and all the messages that have 
remained on the Command Entry display. In addition, the job log contains the 
message help associated with each message, as specified by the CHGJOB 
command. Notice that the job log contains the message help of any message issued 
during the job, not just for the messages issued since the second CHGJOB 
command was entered. 


5722SS1 V5R2M0 020719 Job Log SYSAS727 06/25/02 07:58:53 Page a 
Job name... ......032 QPADEVO007 SOR ss. Sie sae cae prs :  JOHNDOE Number... ......2.23 004201 
Job description ...... : QDFTJOBD IGIBRARY: se a cae eee :  QGPL 

MSGID TYPE SEV DATE TIME FROM PGM LIBRARY INST TO PGM LIBRARY INST 

CPF1124 Information 00 06/25/02 07:57:16.326128 QWTPIIPP Qsys O4FC *EXT 0000 
Message . . . . : Job 004201/JOHNDOE/QPADEV0007 started on 06/25/02 at 

07:57:16 in subsystem QINTER in QSYS. Job entered system on 06/25/02 at 
07:57:16. 

*NONE Request 06/25/02 07:57:50.173112 QMHGSD Qsys 0322 QCMD Qsys 0OB6 
Message... . : -call pgma 

CPF1001 Information 20 06/25/02 07:57:50.189536 PGMA JOHNDOE 000C PGMA JOHNDOE 000C 
Message... . : Detailed message sev 20 - PGMA 
CPF1001 second level text - PGMA 

CPF1002 Information 50 06/25/02 07:57:50.201712 PGMA JOHNDOE 0010 PGMA JOHNDOE 0010 
Message... : Detailed message sev 50 - PGMA 
CPF1002 second evel text - PGMA 

CPF1003 Information 60 06/25/02 STs ols 50.215968 PGMA JOHNDOE 0014 PGMA JOHNDOE 0014 
Message . ... : Detailed message sev 60 - PGMA 
CPF1003 second level text - PGMA 

CPF1004 Information 20 06/25/02 07:57:50.216728 PGMA JOHNDOE 0018 QCMD Qsys OQODE 
Message... H Message sev 20 - PGMA 
CPF1004 second. evel text - PGMA 

CPF1005 Information 50 06/25/02 ee 50.345512 PGMA JOHNDOE 001C QCMD QSsys OODE 
Message... Message sev 50 - PGMA 
CPF1005 second. evel text - PGMA 

CPF1006 Information 60 06/25/02 ee 50.474296 PGMA JOHNDOE 0020 QCMD QsyS QODE 
Message... H Message sev 60 - PGMA 
CPF1006 second evel text - PGMA 

*NONE Request 06/25/02 07:58:31.181888 QMHGSD QSYS 0322 QCMD Qsys 00OB6 
Message... . : -chgjob 1og(3 40 *seclvl) 

*NONE Request 06/25/02 07:58:34.201792 QMHGSD QsYS 0322 QCMD Qsys OOB6 
Message... . : -call pgmc 

CPF1OOF Information 30 06/25/02 07:58:34.330576 PGMC JOHNDOE 000Cc QCMD QSsys QODE 
Message... . Message sev 30 - PGMC 
CPF1O0F second level text - PGMC 

CPF1010 Information 40 06/25/02 07:58:34.459360 PGMC JOHNDOE 0010 QCMD QsyS OQODE 
Message... . 3: Message sev 40 - PGMC 
CPF1010 second level text - PGMC 

*NONE Request 06/25/02 07: 58: 38.128784 QMHGSD QsyS 0322 QCMD QsysS OOB6 
Message... 2: -call pgmd 

*NONE Request 06/25/02 07: 58: 45.386352 QMHGSD QSYS 0322 QcMD QsyS 0OB6 
Message... .: -call pgme 

*NONE Request 06/25/02 07:58:52.643920 QMHGSD QsyS 0322 QCMD Qsys 0OB6 
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Message... .: -signoff *list 


CPF1164 Completion 00 06/25/02 07:58:52.772704 QWTMCEOJ Qsys O1EE *EXT 0000 
Message . . . . : Job 004201/JOHNDOE/QPADEV0007 ended on 06/25/02 at 
07:58:52; 3 seconds used; end code 0. 
Cause. . . . . : Job 004201/JOHNDOE/QPADEVO007 completed on 06/25/02 at 


07:58:52 after it used 3 seconds processing unit time. The job had ending 
code @. The job ended after 1 routing steps with a secondary ending code of 
0. The job ending codes and their meanings are as follows: © - The job 
completed normally. 10 - The job completed normally during controlled ending 
or controlled subsystem ending. 20 - The job exceeded end severity (ENDSEV 
job attribute). 30 - The job ended abnormally. 40 - The job ended before 
becoming active. 50 - The job ended while the job was active. 60 - The 
subsystem ended abnormally while the job was active. 70 - The system ended 
abnormally while the job was active. 80 - The job ended (ENDJOBABN command). 
90 - The job was forced to end after the time limit ended (ENDJOBABN 
command). Recovery .. .: For more information, see the Work Management, 
SC41-8078. 


The headings at the top of each page of the printed job log identify the job to 
which the job log applies and the characteristics of each entry: 


* The fully qualified name of the job (job name, user name, and job number). 
* The name of the job description used to start the job. 

* The date and time the job started. 

* The message identifier. 

* The message type. 

* The message severity. 

* The date and time each message was sent. 


* The message. If the logging level specifies that second-level text is to be 
included, the second-level text appears on subsequent lines below the message. 


* The program or procedure from which the message or request was sent. 


* The instruction number for the machine interface or higher-level statement 
number for the program or procedure from which the message was sent. 


* The program or procedure to which the message or request was sent. 


* The instruction number for the machine interface or the higher-level language 
statement number to which the program or procedure was sent. 


Sending or Receiving Program or Procedure 

When the sender or receiver is an ILE procedure, the message entry contains the 
full name of the procedure (procedure name, module name, and ILE program 
name). When the sender or receiver is an original program model (OPM) program, 
only the OPM program name is shown. 


If the sender or receiver is an OPM program, the corresponding instruction 
number represents an instruction number. There is only one such number. If the 
sender or receiver is an ILE procedure, the instruction number represents a high 
level language statement number rather than an MI instruction number. If the ILE 
procedure has been optimized (maximum efficiency), there may be up to three 
numbers. It is not always possible to determine a single statement number for an 
optimized procedure. If there is more than one number given, each number 
represents a potential point where the procedure was when the message was sent. 
It is also possible that no number can be determined. If this the case, *N appears in 
the message rather than a number. 


The logging levels affect a batch job log in the same way as shown in the 
preceding example. If the job uses APPC, the heading contains a line showing the 
unit of work identifier for APPC. 


Additional Message Filtering 

If the job log is directed to a database file through use of the QMHCTLJL API, 
additional message filtering can be specified. The message filtering specified 
through this API is applied when the job ends and the records for the messages are 
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being written to the file. Up until this time, the messages which are now filtered 
have appeared. Thus they can be seen while the job is running. When the job log is 
written, the messages which are filtered will have no records written to the file for 
them. Thus, even though they appear while the job is running they will not appear 
in the final file that is produced. 


Displaying the Job Log 
The way to display a job log depends on the status of the job. 


* If the job has ended and the job log is not yet printed, use the Display Spooled 
File (DSPSPLF) command, as follows: 


DSPSPLF FILE(QPJOBLOG) JOB(001293/FRED/WS3) 


to display the job logs for job number 001293 associated with user FRED at 
display station WS3. 


* If the job is still active (batch or interactive jobs) or is on a job queue and has 
not yet started, use the Display Job Log (DSPJOBLOG) command. For example, 
to display the job log of the interactive job for user JSMITH at display station 
WSI, enter: 


DSPJOBLOG JOB(nnnnnn/JSMITH/WS1) 
where nnnnnn is the job number. 


To display the job log of your own interactive job, do one of the following: 
* Enter the following command: 
DSPJOBLOG 


* Enter the WRKJOB command and select option 10 (Display job log) from the 
Work with Job display. 


* Press F10=Include detailed messages from the Command Entry display (this key 
displays the messages that are shown in the job log). 


* If the input-inhibited light on your display station is on and remains on, do the 
following: 


1. Press the System Request key, then press the Enter key. 

2. On the System Request menu, select option 3 (Display current job). 

3. On the Display Job menu, select option 10 (Display Job log, if active or on 
job queue). 

4. On the Job Log display, DSPJOB appears as the processing request. Press F10 
(Display detailed messages). 


5. On the Display All Messages display, press the Roll Down key to see 
messages that were received before you pressed the System Request key. 


* Sign off the work station, specifying LOG(*LIST) on the SIGNOFF command. 
When you use the Display Job Log (DSPJOBLOG) command, you see the Job Log 
display. This display shows program names with special symbols, as follows: 


>> The running command or the next command to be run. For example, if a 
program was called, the call to the program is shown. 


> The command has completed processing. 
The command has not yet been processed. 
? Reply message. This symbol marks both those messages needing a reply 


and those that have been answered. 


On the Job Log display, you can do the following: 
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* Press F10 to display detailed messages. This display shows the commands or 
operations that were run within an HLL program or within a CL program or 
procedure for which LOG is activated. 


* Use the cursor movement keys to get to the end of the job log. To get to the end 
of the job log quickly, press F18 (Bottom). After pressing F18, you might need to 
roll down to see the command that is running. 


* Use the cursor movement keys to get to the top of the job log. To get to the top 
of the job log quickly, press F17 (Top). 


You may use the DSPJOBLOG command to direct the job to a database file instead 
of having it printed or displayed. There are two options available. In the first 
option, you may specify a file and member name on the command. In this option, 
the primary job log information is written to the database file specified on the 
command. In the second option you may use the command in conjunction with the 
information provided on the QMHCTLJL API which was run previously. In this 
option, the job log is written to the file(s) specified on the API call. With this 
option, both primary and secondary files can be produced and message filtering 
can be performed as the messages are written to the file. With both these options, 
when the DSPJOBLOG command completes, the output will not be displayed nor 
will there be a spooled file available for printing. 


Preventing the Production of Job Logs 

To prevent a job log from being produced at the completion of a batch job, you can 
specify *NOLIST for the message text-level value of the LOG parameter on the 
Batch Job (BCHJOB), Submit Job (SBMJOB), Change Job (CHGJOB), Create Job 
Description (CRTJOBD), or Change Job Description (CHGJOBD) command. If you 
specify *NOLIST for the message level value of the LOG parameter, the job log is 
not produced at the end of a job unless the job end code is 20 or greater. If the job 
end is 20 or greater, the job log is produced. 


For an interactive job, the value specified for the LOG parameter on the SIGNOFF 
command takes precedence over the LOG parameter value specified for the job. 


Job Log Considerations 

The following suggestions apply to using job logs: 

* To change the output queue for all jobs on the system, use the OUTQ or DEV 
parameter on the Change Printer File (CHGPRTF) command to change the file 
QSYS/QPJOBLOG. The following are two examples using each of the 
parameters: 


CHGPRTF FILE(QSYS/QPJOBLOG) 
DEV (USRPRT) 


or 


CHGPRTF FILE(QSYS/QPJOBLOG) 
OUTQ(USROUTQ) 

* To change the QPJOBLOG printer file to use output queue QEZJOBLOG, use the 
Operational Assistant cleanup function. When you want to use automatic 
cleanup of the job logs, the printer files must be directed to this output queue. 
For more information on the Operational Assistant cleanup function, see the 
Getting Started with iSeries topic Systems management category of the iSeries 
Information Center. 


* To specify the output queue to which a job’s job log is written, make sure that 
file QPJOBLOG has OUTQ(*JOB) specified. You can use the OUTQ parameter on 
any of the following commands: BCHJOB, CRTJOBD, CHGJOBD, or CHGJOB. 
The following is an example: 
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CHGJOB OUTQ(*JOB) 


If you change the default OUTQ at the beginning of the job, all spooled files are 
affected. If you change it just before job completion, only the job log is affected. 
You cannot use the Override with Printer File (OVRPRTF) command to affect the 
job log. 

* If the output queue for a job cannot be found, no job log is produced. 


* To hold all job logs, specify HOLD(*YES) on the CHGPRIF command for the file 
QSYS/QPJOBLOG. The job logs are then released to the writer when the Release 
Spooled File (RLSSPLF) command is run. The following is an example: 

CHGPRTF FILE(QSYS/QPJOBLOG) 
HOLD(*YES) 

* If the system abnormally ends, the start prompt allows the system operator to 
specify whether the job logs are to be printed for any jobs that were active at the 
time of the abnormal end. 


* To delete a job log, use the Delete Spooled File (DLTSPLF) command or the 
Delete option on the output queue display. 


* If you used the USRDTA parameter on the Change Print File (CHGPRTF) 
command to change the user data value for the QSYS/QPJOBLOG file, the value 
specified will not be shown on the Work with Output Queue or Work with All 
Spooled Files displays. The value shown in the user data column is the job name 
of the job whose job log has printed. 


* If job logs are being analyzed by programming technique, use the QMHCTLJL 
API to direct the job log to the database file(s). The format of the records in the 
database file is guaranteed while the printed format is not. If new fields need to 
be added to a job log record, they are added at the end of the record so existing 
programs will continue to work. Query features provided by the system can be 
used directly on the files. 


Considerations for Interactive Job Logs 

The IBM-supplied job descriptions QCTL, QINTER, and QPGMR all have a log 
level of LOG(4 0 *NOLIST); therefore, all messages and both first- and second-level 
text for the messages are written to the job log. However, the job logs are not 
printed unless you specify *LIST on the SIGNOFF command. To change the log 
level for interactive jobs, you can use the CHGJOB or CHGJOBD command. 


If a display station user uses an IBM-supplied menu or the command entry 
display, all error messages are displayed. If the display station user uses a 
user-written initial program, any unmonitored message causes the initial program 
to end and a job log to be produced. However, if the initial program monitors for 
messages, it receives control when a message is received. In this case, it may be 
important to ensure that the job log is produced so you can determine the specific 
error that occurred. For example, assume that the initial program displays a menu 
that includes a sign-off option, which defaults to *NOLIST. The initial program 
monitors for all exceptions and includes a Change Variable (CHGVAR) command 
that changes the sign-off option to *LIST if an exception occurs: 

PGM 


DCLF MENU 
DCL &SIGNOFFOPT TYPE(*CHAR) LEN(7) VALUE(*NOLIST) 


MONMSG MSG(CPFQ000) EXEC(GOTO ERROR) 
PROMPT: SNDRCVF RCDFMT (PROMPT) 
CHGVAR &IN41 '0' 
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IF (&OPTION *EQ '90') SIGNOFF LOG(&SIGNOFFOPT) 


GOTO PROMPT 
ERROR: CHGVAR &SIGNOFFOPT '*LIST' 
CHGVAR &IN41 '1' 
GOTO PROMPT 
ENDPGM 


If an exception occurs in the previous example, the CHGVAR command changes 
the option on the SIGNOFF command to *LIST and sets on an indicator. This 
indicator could be used to condition a constant that displays a message informing 
the display station user that an unexpected event has occurred and telling him 
what to do. 


If the interactive job is running a CL program or procedure, the CL commands are 
logged only if the log level is 3 or 4 and one of the following is true: 


* You specified LOG(*YES) on the Create Control Language Program 
(CRTCLPGM) command, the Create Control Language Module (CRTCLMOD) 
command, or the Create Bound CL Program (CRTBNDCL) command. 


* You specified LOG(*JOB) on the Create Control Language Program 
(CRTCLPGM) command, the Create Control Language Module (CRTCLMOD) 
command, or the Create Bound CL Program (CRTBNDCL) command, and 
(*YES) is the current LOGCLPGM job attribute. 


You can set and change the LOGCLPGM job attribute by using the LOGCLPGM 
parameter on the SBMJOB, CRTJOBD, CRTIJOBD, and CHGJOBD commands. 


Considerations for Batch Job Logs 

For your batch applications, you may want to change the amount of information 
logged. The log level (LOG(4 0 *NOLIST)) specified in the job description for the 
IBM-supplied subsystem QBATCH supplies a complete log if the job abnormally 
ends. If the job completes normally, no job log is produced. 


If you want to print the job log in all cases, use the Change Job Description 
(CHGJOBD) command to change the job description, or specify a different LOG 
value on the BCHJOB or SBMJOB command. See a , 
description of logging levels. 


If a batch job is running a CL program or procedure, the CL commands are always 
logged if you specify LOG(*YES) when you create modules or programs using the 
following commands: 


* Create Control Language Program (CRTCLPGM) 
* Create Control Language Module (CRTCLMOD) 
* Create Bound Control Language Program (CRTBNDCL) 


CL commands are also logged if you specify LOGCLPGM(*YES) when you use the 
CHGJOB command and the SBMJOB command. 


QHST History Log 


The history log (QHST) consists of a message queue and a physical file known as a 
log-version. Messages sent to the history log message queue are written by the 
system to the current log version physical file. 
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* History log (QHST). Contains a high-level trace of system activities such as 
system, subsystem, and job information, device status, and system operator 
messages. Its message queue is QHST. 


When a log-version is full, a new version of the log is automatically created. Each 
version is a physical file that is named in the following way: 


Qxxxyydddn 


where: 
XXX Is a 3-character description of the log type (HST) 
yyddd Is the Julian date of the first message in the log version 


n Is a sequence number within the Julian date (A through Z and 0 through 
9)? 


Note: The number of records in each version of the history log is specified in the 
system value QHSTLOGSIZ. 


The text of the log version file contains the date and time of the first message and 
last message in the log version. The date and time of the first message are in 
positions 1-13 of the text; the date and time of the last message are in positions 
14-26. The date and time are in the format cyymmddhhmmss, where: 


c Is the century guard digit 
yymmdd Is the date the message was sent 


hhmmss Is the time the message was sent 


You can create a maximum of 36 log versions with the same Julian date. If more 
than 36 log versions are created on the same day, the next available Julian day is 
used for subsequent log versions. If some of the older log versions are then 
deleted, it is possible to use the names again. Log versions are out of order when 
sequenced by name if log versions are deleted and names used again. 


You can also write a program to process history log records. Because several 
versions of each log may be available, you must select the log-version to be 
processed. To determine the available log-versions, use the Display Object 
Description (DSPOBJD) command. For example, the following DSPOBJD command 
displays what versions of the history log are available: 


DSPOBJD OBJ(QSYS/QHST*) | OBJTYPE(*FILE) 


You can delete logs on your system by using the delete option from the display 
that is presented on the Work with Objects (WRKOBJ) command. 


You can display or print the information in a log using the Display Log (DSPLOG) 
command. You can select the information you want displayed or printed by 
specifying any combination of the following: 


* Period of time 
* Name of job that sent the log entry 
* Message identifiers of entries 


The following DSPLOG command displays all the available entries for the job 
OEDAILY in the current day: 


DSPLOG JOB(OEDAILY) 
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The resulting display is: 
y 


cE 
Display History Log Contents 
Job OEDAILY started 
Database file OEMSTR in library OELIB expired 
Job OEDAILY abnormally ended 
Job OEDAILY started 
Job OEDAILY ended 
Bottom 
Press Enter to continue. 
F3=Exit F10=Display all F12=Cancel 
S y 


If you reset the system date or time to an earlier setting, or if you advanced the 
system date and time by more than 48 hours, a new log version is started. This 
ensures that all messages in a single log version are in chronological order. 


Log versions created on a release prior to V3R6MO may contain entries that are not 
in chronological order if the system date and time was reset to an earlier setting. 
Therefore, when you try to display the log-version, some entries may be missed. 
For example, if the log-version contains entries dated 1988 followed by entries 
dated 1987, and you want to display those 1987 entries, you specify the 1987 dates 
on the PERIOD parameter on the DSPLOG command but the expected entries are 
not displayed. You should always use the system date (QDATE) and the system 
time (QTIME), or you should specify the PERIOD parameter as follows: 


PERIOD((start-time start-date) (*AVAIL *END)) 


The system writes the messages sent to a log message queue to the current version 
physical file when the message queue is full or when the DSPLOG command was 
used. If you want to ensure the current version is up-to-date, specify a fictitious 
message identifier, such as ###0000, on the DSPLOG command. No messages are 
displayed, but the log-version physical file is made current. 


If you print the information in a log using the Display Log command and output 
parameter *PRINT, (DSPLOG OUTPUT(*PRINT), only one line from each message 
is printed, using the first 105 characters of each message. 


If you print the information in a log using the Display Log command and output 
parameter *PRTWRAP, (DSPLOG OUTPUT(*PRTWRAP), messages longer than 105 
characters are wrapped to include additional lines to a limit of 2000 characters. 


If you print the information in a log using the Display Log command and output 
parameter *PRTSECLVL, messages longer than 105 characters are wrapped to 
include additional lines to a limit of 2000 characters. The second-level message text 
is also printed if available, up to a maximum of 6000 characters. 
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If you display the information in a log using the Display Log (DSPLOG) 
command, only 105 characters of message text are shown. Any characters after 105 
characters are truncated at the right. 


Format of the History Log 


A database file is used to store the messages sent to a log on the system. Because 

all records in a physical file have the same length and messages sent to a log have 

different lengths, the messages can span more than one record. Each record for a 

message has three fields: 

* System date and time (a character field of length 8). This is an internal field. The 
converted date and time also are in the message. 


* Record number (a 2-byte field). For example, the field contains hex 0001 for the 
first record, hex 0002 for the second record, and so on. 


* Data (a character field of length 132). 


The third field (data) of the first record has the following format: 


Contents Type Length Positions in Record 
Job name Character 26 11-36 
Converted date and_ | Character 13 37-49 
time’ 

Message ID Character 7 50-56 
Message file name Character 10 57-66 
Library name Character 10 67-76 
Message type” Character 2 77-78 
Severity code Character 2 79-80 
Sending program Character 12 81-92 
name? 

Sending program Character 4 93-96 
instruction number* 

Receiving program Character 10 97-106 
name 

Receiving program Character 4 107-110 
instruction number* 

Message text length | Binary 2 111-112 
Message data length | Binary 2 113-114 
Coded character set | Binary 4 115-118 


identifier (CCSID) for 
text or data® 


Reserved Character 24 119-142 
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Contents Type Length Positions in Record 


The format is: cyymmddhhmmss 

where: 

c Is the century digit (c=0 if yy 2 40, c = 1 if yy < 40) 
yymmdd Is the year, month, and day that the message is sent 
hhmmss Is the hour, minute, and second that the message is sent 


2 This has the same value as the RTNTYPE parameter on the Receive Message 
(RCVMSG) command. 


3 If the sender or receiver is an ILE procedure, the entry in the history log contains 
only the ILE program name. The module name and procedure name are not 
included in the history log. 


. If the sender or receiver is an ILE procedure, the sending or receiving instruction 
number is 0. 


7 This CCSID applies only to the message data that is defined as *CCHAR data if 
the message is a stored message. The rest of the message data can be considered 
65 535. Otherwise, this is the CCSID of the immediate message. 


The third field (data) of the remaining records has the following format: 


Contents Type Length 


Message Character Variable! 


Message data Character Variable” 


. This length is specified in the first record (positions 111 and 112) and cannot 
exceed 132. 


7 This length is specified in the first record (positions 113 and 114). 


A message is never split when a new version of a log is started. The first and last 
records of a message are always in the same QHST version. 


Processing the QHST File 


If you use an HLL program to process the QHST file, keep in mind that the length 
of the message can vary with each occurrence of a message. Because the message 
includes replaceable variables, the actual length of the message varies; therefore, 
the message data begins at a variable location for each use of the same message. 


QHST Job Start and Completion Messages 


The system performs special formatting of the job start and job completion 
messages. For message CPF1124 (job start) and message CPF1164 (job completion), 
the message data always begins in position 11 of the third record. 


Job accounting provides more information than CPF1124 and CPF1164. For simple 
job accounting functions, use the CPF1164 message. 
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Performance information is not displayed as text on message CPF1164. Because the 
message is in the QHST log, users can write application programs to retrieve this 
data. The format of this performance information is as follows. 


The performance information is passed as a variable length replacement text value. 
This means that the data is in a structure with the first entry being the length of 
the data. The size of the length field is not included in the length. The first data 
fields in the structure are the times and dates that the job entered the system and 
when the first routing step for the job was started. The times are in the format 
‘hh:mm:ss’. The separators are always colons. The dates are in the format defined 
in the system value QDATFMT and the separators are in the system value 
QDATSEP. The time and date the job entered the system precede the job start time 
and date in the structure. 


The time and date the job entered the system are when the system becomes aware 
of a job to be initiated (a job structure is set aside for the job). For an interactive 
job, the job entry time is the time the password is recognized by the system. For a 
batch job, it is the time the BCHJOB or SBMJOB command is processed. For a 
monitor job, reader or writer, it is the time the corresponding start command is 
processed, and for autostart jobs it is during the start of the subsystem. 


Following the times and dates are the total response time and the number of 
transactions. The total response time is in seconds and contains the accumulated 
value of all the intervals the job was processing between pressing the Enter key at 
the work station and when the next display is shown. This information is similar 
to that shown on the WRKACTIJOB display. This field is only meaningful for 
interactive jobs. 


It is also possible in the case of a system failure or abnormal job end that the last 
transaction will not be included in the total. The job end code in this case would 
be a 40 or greater. The transaction count is also only meaningful for interactive jobs 
other than the console job and is the number of response time intervals counted by 
the system during the job. 


The number of synchronous auxiliary I/O operations follows the number of 
transactions. This is the same as the AUXIO field that appears on the 
WRKACTIJOB display except that this value is the total for the job. If the job ends 
with a end code of 70, this value may not contain the count for the final routing 
step. Additionally, if a job exists across an IPL (using a TFRBCHJOB command) it 
is ended before becoming active following an IPL, the value is 0. 

The final field in the performance statistics is the job type. Values for this field are: 
Automatically started job 

Batch job 

Interactive job 

Subsystem monitor 

Spooling reader 

System job 


Spooling writer 


xs nF Zw DP 


Start job 
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For messages in which the message data begins in a variable position, you can 
access the message data by doing the following: 


* Determine the length of the variables in the message. For example, assume that 
a message uses the following five variables: 


Job name *CHAR 10 
User name  ¥*CHAR 10 
Job number *CHAR 6 
Time *CHAR 8 
Date *CHAR 8 


These variables are fixed in the first 42 positions of the message data. 
* To find the location of the message data, consider that: 
— The message always begins in position 11 of the second record. 


— The length of the message is stored in a 2-position field beginning at position 
111 of the first record. This length is stored in a binary value so if the message 
length is 60, the field contains hex 003C. 


Then, by using the length of the message and the start position of the message, 
you can determine the location of the message data. 


Deleting QHST Files 


Log-version physical files accumulate on a system and you should periodically 
delete old logs that are not needed. A log-version is created such that only the 
security officer is authorized to delete it. 


The Operational Assistant* provides a cleanup function which includes the deletion 
of old QHST files. Another alternative is: 


* As the security officer, specify: 
WRKOBJ OBJ(QSYS/QHST*) OBJTYPE(*FILE) 


Use option 4 to delete old unneeded files. 
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Chapter 9. Defining Commands 


A CL command is a statement that requests that the system perform a function. 
Enterring the command starts a program that performs the function. CL commands 
allow you to request a broad range of functions. You can use these IBM-supplied 
commands, change the default values that are supplied by IBM, define your own 
commands. This chapter describes how you can define and create your own 
commands. If you need help with the abbreviations of CL commands and 


keywords, see [Appendix 


Overview of How to Define Commands 


The following illustration shows the steps to create a command. The text that 
follows the illustration describes each step. 


Command Definition 
Statments 


Display 


Create 
Command 
Command 


Command 
Definition 
Object 


Command Validity Prompt 
Processing Checker Override 
Program Program Program 


RBAFN543-0 


Writing your own validity checking and prompt override programs are optional 
steps. 
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Step Description 


Command Definition Statements 

The command definition statements contain the information that is necessary to 
prompt the work station user for input, to validate that input, and to define the 
values to be passed to the program that is called when the command is run. 


Command definition statements may exist in any file supported as input to the 
CRTCMD command. For example, source entry utility (SEU) source files, diskette 
files, and other device files may contain command definition statements. They are 
usually entered in a source file by SEU. [able contains the statements used for 
defining commands. 


Table 8. Statements for Defining CL Commands 


Statement Type Statement Name Description 


Command CMD Specifies the prompt text, if any, for 
the command name 


Parameter PARM Defines a parameter or key 
parameter for a command 


Element ELEM Defines an element in a list used as 
a parameter value 


Qualifier QUAL Defines a qualifier of a name used 
as a parameter 

Dependent DEP Defines the relationship among 
parameters 

Prompt Control PMTCTL Defines the conditions under which 


certain parameters are prompted. 


Create Command (CRTCMD) Command 

The CRT'CMD command processes the command definition statements to create 
the command definition object. The CRTCMD command may be run interactively 
or in a batch job. 


Command Definition Object 
The command definition object is the object that is checked by a system program 
to ensure that the command is valid and that the proper parameters were entered. 


Validity Checking 
The system performs validity checking on commands. You may also write your 
own validity checking program although it is not required. 


The validity checking performed by the system ensures that: 
* Values for the required parameters are entered. 
* Each parameter value meets data type and length requirements. 


* Each parameter value meets optional requirements specified in the command 
definition of: 
— A list of valid values 
— Arange of values 
— Arelational comparison to a value 


* Conflicting parameters are not entered. 


The system performs validity checking when: 
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* Commands are entered interactively from a display station. 

* Commands are entered from a batch input stream using spooling. 

* Commands are entered into a database file through the source entry utility 
(SEU). 


* A command is passed to the QCMDEXC, QCMDCHK, or QCAPCMD program 
by a call from a HLL. See for more information on the QCMDEXC 
program. 


* ACL module or OPM program is created. 
* Commands are run by a CL procedure or program or a REXX procedure. 


* A command is run using the C language system function. 


rogram called _a validity checking program (see Writing a Validity Checking 
See ETT or you can include the checking i in the command 


processing program. You specify the names of both the command processing and 
validity checking programs on the CRTCMD command. 


If a command has a validity checking program, the system passes the command 
parameter values to the validity checking program. This happens before the system 
calls the command processing program. A validity checking program runs during 
syntax checking during the following conditions: 


* When running the command. 


* When using the source entry utility (SEU) to enter commands into a CL source 
member and the programmer uses constants instead of variables for the 
parameters that are specified on the command. 


* When compiling a CL program or procedure that uses constants instead of 
variables for all the parameters that are specified on the command. 


When the program finds an error, the user receives a message to allow immediate 
correction of errors. The command processing program can assume that the data 


that is passed to it is correct. Refer to era 
een for further information on writing calaiey checking programs. 


Prompt Override Program 

You can write prompt override programs to supply current values for parameter 

defaults when prompting the command. For example, prompt override programs 

are frequently used on Change commands to supply values for parameters with a 

default value of *SAME. See a 
for more details. A pion: everide program is optional. 


Providing Help Information for Commands 
To provide online help information for your command, you can use help panel 
groups. A panel group is an object with type *PNLGRP. For more information on 


help panel groups, see the [App 


Command Processing Program 

The command processing program (CPP) is the program that the command 
analyzer calls to perform the function requested. The CPP can be a CL program, 
another HLL program, or a REXX procedure. For example, it can be an application 
program that your command calls, or it can be a CL program or REXX procedure 
that contains a system command or series of commands. 


The CPP must accept the parameters as defined by the command definition 
statements. 
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Command Exit Programs and Independent ASPs 

Any exit program, including the command processing program, validity checking 
program, prompt override program, choices program, or prompt control program, 
needed by a command must be in the same independent auxiliary storage pool 
(ASP) as the command, or in the system ASP (ASP 1), or in a basic ASP (ASPs 
2-32). The command must not be in one independent ASP and the exit programs in 
another independent ASP. Problems could occur when running the command if the 
independent ASP where these exit programs reside is not available (for example, if 
the independent ASP device is varied off). 


Authority Needed for the Commands You Define 


For users to use a command you create, they must have operational authority to 
the command and data authority to the command processing program and 
optional validity checking program. They also must have read authority to the 
library that contains the command, to the command processing program, and to 
the validity checking program. If the command processing program or the validity 
checking program refers to any service programs, the user must have execute 
authority to the service programs and to the service program libraries. The user 
must have the execute authority to the programs that are listed below. 


* Command Processing Program (CPP). 

* Validity Checking Program (VCP). 

* Any service programs that are used by the CPP or VCP. 

* The libraries that contain the CPP, VCP, and service programs. 


The user must also have the proper authority to any other commands run in the 
command processing programs. The user must also have authority to the files to 
open them. 


Example of Creating a Command 


If you want to create a command to allow the system operator to call a program to 
start the system, you would do the following. (This example assumes you are 
using IBM-supplied source files.) 


1. Enter the command definition source statement into the source file QCMDSRC 
using the member name of STARTUP. 


CMD PROMPT('S Command for STARTUP') 
2. Create the command by entering the following command. 
CRTCMD CMD(S) PGM(STARTUP) SRCMBR(STARTUP) 


3. Enter the source statements for the STARTUP program (the command 
processing program). 
PGM 
STRSBS QINTER 
STRSBS QBATCH 
STRSBS QSPL 
STRPRTWTR DEV(QSYSPRT) OUTQ(QPRINT) WTR(WTR) 
STRPRTWTR DEV(WSPR2) OUTQ(WSPRINT) WTR(WTR2) 
SNDPGMMSG MSG('STARTUP procedure completed') MSGTYPE(*COMP) 
ENDPGM 
4. Create the program using the Create Bound CL Program (CRTBNDCL) 
command. 


CRTBNDCL STARTUP 
In the previous example, S is the name of the new command (specified by the 
CMD parameter). STARTUP is the name of the command processing program 


(specified by the PGM parameter) and also the name of the source member that 
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contains the command definition statement (specified by the SRCMBR parameter). 
Now the system operator can either enter S to call the command or CALL STARTUP 
to call the command processing program. 


How to Define Commands 


To create a command, you must first define the command through command 
definition statements. Refer to the CL section of the Programming category of the 
iSeries Information Center for details. The general format of the command 
definition statements and a summary of the coding rules follow. 


Statement 
Coding Rules 


CMD _ One and only one CMD statement must be used. The CMD statement can 
be placed anywhere in the source file. 


PARM A maximum of 75 PARM statements is allowed. The order in which you 
enter the PARM statements into the source file determines the order in 
which the parameters are passed to the command processing program 
(CPP) and validity checking program (VCP). One PARM statement is 
required for each parameter that is to be passed to the command 
processing program. To specify a parameter as a key parameter, you must 
specify KEYPARM(*YES) for the PARM statement. The number of 
parameters coded with KEYPARM(*YES) should be limited to the number 
needed to uniquely define the object to be changed. To use key parameters, 
the prompt override program must be specified when creating the 
command. Key parameters can not be defined with PMTCTL(*PMTRQS) or 
(PMTCTL(label). 


ELEM A maximum of 300 ELEM statements is allowed in one list. The order in 
which you enter the ELEM statements into the source file determines the 
order of the elements in the list. The first ELEM statement must have a 
statement label that matches the statement label on the TYPE parameter on 
the PARM or ELEM statement for the list. 


QUAL A maximum of 300 qualifiers is allowed for a qualified name. The order in 
which you enter the QUAL statements into the source file determines the 
order in which the qualifiers must be specified and the order in which they 
are passed to the validity checking program and command processing 
program. 


DEP The DEP statement must be placed after all PARM statements it refers to. 
Therefore, the DEP statements are normally placed near the end of the 
source file. 


PMTCTL 
The PMTCTL statement must be placed after all PARM statements it refers 
to. Therefore, the PMTCTL statements are normally placed at the end of 
the source file. 


At least one PARM statement must precede any ELEM or QUAL statements in the 
source file. The source file in which you enter the command definition statements 
is used by the CRTCMD command when you create_a command. For information 
on entering statements into a source file, see the 


[ni GE book. 
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Using the CMD Statement 


When you define a command, you must include one and only one CMD statement 
with your command definition statements. 


When you define a command, you can provide command prompt text for the user. 
If the user chooses to be prompted for the command instead of entering the entire 
command, the user types in the command name and presses F4 (Prompt). The 
command prompt is then displayed with the command name and the heading 
prompt text on line 1 of the display. 


If you want to specify prompt text for the command, use the PROMPT parameter 
on the CMD statement to specify the heading for the prompt. You then specify the 
prompts for the parameters, elements of a list, and qualifiers on the PROMPT 
parameters for the PARM, ELEM, and QUAL statements. 


On the PROMPT parameter for the CMD statement, you can specify the actual 
prompt heading text as a character string 30 characters maximum, or you can 
specify the message identifier of a message description. In the following example, a 
character string is specified for the command ORDENTRY. 


CMD PROMPT('Order Entry') 


Line 1 of the prompt looks like this after the user types in the command name and 
presses P4. 


Order Entry (ORDENTRY) 


If you do not provide prompt text for the command you are defining, you only 
need to use the word CMD for the CMD statement. However, you may want to 
use the PROMPT keyword for documentation purposes. 


Defining Parameters 


You can define as many as 75 parameters for each command. To define a 
parameter, you must use the PARM statement. 


On the PARM statement, you specify the following: 
* Name of the keyword for the parameter 

* Whether or not the parameter is a key parameter 
* Type of parameter value that can be passed 

* Length of the value 

* If needed, the default value for the parameter. 


In addition, you must consider the following information when defining 
parameters. (The associated PARM statement parameter is given in parentheses.) 


* Whether a value is returned by the command processing program (RTNVAL). If 
RINVAL (*YES) is specified, a return variable must be coded on the command 
when it is called, if you want to have the value returned. If no variable is 
specified for a RTNVAL(*YES) parameter, a null pointer is passed to the 
command processing program. 


* Whether the parameter is not to appear on the prompt to the user but is to be 
passed to the command processing program as a constant (CONSTANT). 


* Whether the parameter is restricted (RSTD) to specific values (specified on the 
VALUES, SPCVAL, or SNGVAL parameter) or can include any value that 
matches the parameter type, length, value range, and a specified relationship. 
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* What the specific valid parameter values are (VALUES, SPCVAL, and SNGVAL). 


* What tests should be performed on the parameter value to determine its validity 
(REL and RANGE). 


¢ Whether the parameter is optional or required (MIN). 


* How many values can be specified for a parameter that requires a simple list 
(MIN and MAX). 


* Whether unprintable data (any character with a value of hexadecimal 00 through 
3F or FF can be entered for the parameter value (ALWUNPRT). 


* Whether a variable name can be entered for the parameter value (ALWVAR). 
* Whether the value is a program name (PGM). 

¢ Whether the value is a data area name (DTAARA). 

* Whether the value is a file name (FILE). 

* Whether the value must be the exact length specified (FULL). 

* Whether the length of the value should be given with the value (VARY). 

* Whether expressions can be specified for a parameter value (EXPR). 


* Whether attribute information should be given about the value passed for the 
parameter (PASSATR). 


* Whether to pass a value to the command processing program or validity 
checking program if the parameter being defined is not specified (PASSVAL). 

* Whether the case value is preserved or the case value is converted to uppercase 
(CASE). 

* Whether list within list displacements (LISTDSPL) are 2-byte or 4-byte binary 
values. 


* What the message identifier is or what the prompt text for the parameter is 
(PROMPT). 


* What valid values are shown in the possible choices field on the prompt display 
(CHOICE). 


* Whether the choice values are provided by a program (CHOICEPGM). 


* Whether prompting for a parameter is controlled by another parameter 
(PMTCTL). 


* Whether values for a PMTCTL statement are provided by a program (for 
parameters referred to in CTL keywords) (PMTCTLPGM). 


* Whether the value is to be hidden in the job log or hidden when the command 
is being prompted (DSPINPUT). 


Naming the Keyword for the Parameter 

The name of the keyword you choose for a parameter should be descriptive of the 
information being requested in the parameter value. For example, USER for user 
name, CMPVAL for compare value, and OETYPE for order entry type. The 
keyword can be as long as 10 alphanumeric characters, the first of which must be 
alphabetic. 


Parameter Types 

The basic parameter types are (parameter TYPE value given in parentheses): 

* Decimal (*DEC). The parameter value is a decimal number, which is passed to 
the command processing program as a packed decimal value of the length 
specified on the LEN parameter. Values specified with more fractional digits 
than defined for the parameter are truncated. 


* Logical (*LGL). The parameter value is a logical value, ‘1’ or ’0’, which is passed 
to the command processing program as a character string of length 1 (F1 or FO). 
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* Character (*CHAR). The parameter value is a character string, which can be 
enclosed in apostrophes and which is passed to the command processing 
program as a character string of the length specified on the LEN parameter. The 
value is passed with its apostrophes removed, is left-justified, and is padded 
with blanks. 


* Name (*NAME). The parameter value is a character string that represents a basic 
name. The maximum length of the name is 256 characters. The first character is 
alphabetic (A-Z), $, #, or @. The remaining characters are the same as the first 
character, but can also include the numbers 0 through 9, underscores (_), and 
periods (.). The name can also be a string of characters that begin and end with 
double quotation marks ("). The system passes the value to the command 
processing program as a character string of the length specified in the LEN 
parameter. The value is left-justified and padded with blanks. Normally, you use 
the *NAME type for object names. If you can enter a special value such as *LIBL 
or *NONE for the name parameter, you must describe the special value on the 
SPCVAL parameter. Then, if the display station user enters one of the allowed 
special values for the parameter, the system bypasses the rules for name 
verification. 


* Simple name (*SNAME). The parameter value is a character string that follows 
the same naming rules as *NAME, except that no periods (.) are allowed. 


* Communications name (*CNAME). The parameter value is a character string 
that follows the same naming rules as *NAME, except that no periods (.) or 
underscores (_) are allowed. 


* Path name (*PNAME). The parameter value is a character string, which can be 
enclosed in apostrophes and which is passed to the command processing 
program as a character string of the length specified on the LEN parameter. The 
value is passed with its apostrophes removed, is left-justified, and is padded 
with blanks. 


* Generic name (*“GENERIC). The parameter value is a generic name, which ends 
with an asterisk (*). If the name does not end with an asterisk, then the generic 
name is assumed to be a complete object name. A generic name identifies a 
group of objects whose names all begin with the characters preceding the 
asterisk. For example, INV* identifies the objects whose names begin with INV, 
such as INV, INVOICE, and INVENTORY. The generic name is passed to the 
command processing program so that it can find the object names beginning 
with the characters in the generic name. 


* Date (*DATE). The parameter value is a character string that is passed to the 
command processing program. The character string uses the format cyymmdd (c = 
century digit, y = year, m = month, d = day). The system sets the century digit 
based on the year specified on the date parameter for the command. If the 
specified year contained 4 digits, the system sets the century digit to 0 for years 
that start with 19. The system sets the century digit to 1 for years that start with 
20. For years that are specified with 2 digits, the system sets the century digit to 
0 if yy equals a number from 40 to 99. However, if yy equals a number from 00 
through 39, the system sets the century digit to 1. The user must enter the date 
on the date parameter of the command in the format that is specified by the 
date format (DATFMT) job attribute. The date separator (DATSEP) job attribute 
determines the optional separator character to use for entering the date. Use the 
Change Job (CHGJOB) command to change the DATFMT and DATSET job 
attributes . The program reads dates with 2-digit years to be in the range of 
January 1, 1940, to December 31, 2039. Dates with 4-digit years must be in the 
range of August 24, 1928, to May 9, 2071. 


* Time (*TIME). The parameter value is a character string. The system passes this 
string to the command processing program in the format hhmmss (h = hour, m = 
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minute, s = second). The time separator (TIMSEP) job attribute determines the 
optional separator to use for entering the time. Use the Change Job (CHGJOB) 
command to change the TIMSEP job attribute. 


Hexadecimal (*HEX). The parameter value is a hexadecimal value. The 
characters specified must be 0 through F. The value is passed to the CPP as 
hexadecimal (EBCDIC) characters (2 hexadecimal digits per byte), and is right 
adjusted and padded with zeros. If the value is enclosed in apostrophes, an even 
number of digits is required. 


Zero elements (*ZEROELEM). The parameter value is considered to be a list of 
zero elements for which no value can be specified in the command. This 
parameter type is used to prevent a value from being entered for a parameter 
that is a list even though the command processing program (CPP) expects a 
value. For example, if two commands use the same CPP, one command could 
pass a list for a parameter, and the other command may not have any values to 
pass. The parameter for the second command would be defined with 
TYPE(*ZEROELEM). 


Integer (*INT2 or *INT4). The parameter value is an integer that is passed as a 
2-byte or 4-byte signed binary number. CL does not support a binary variable 
type. However, you can declare binary numbers in a CL procedure or program 
as variables of TYPE(*CHAR) and process them with the %BINARY built-in 
function. 


Unassigned integer (*UINT2 or *UINT4). The parameter value is an integer that 
is passed as a 2-byte or 4-byte unsigned binary number. CL does not support a 
binary variable type. However, you can declare binary numbers in a CL 
procedure or program as variables of TYPE(*CHAR) and process them with the 
%BINARY built-in function. 


Null (*“NULL). The parameter value is a null pointer, which is always passed to 
the command processing program as a place holder. The only PARM keywords 
valid for this parameter type are KWD, MIN, and MAX. 


Command string (*CMDSTR). The parameter value is a command. You can use 
CL variables to specify parameters in the command that are specified in the 
*CMDSTR parameter. However, you cannot use them to specify the entire 
*CMDSTR parameter. For example, "SBMJOB CMD(DSPLIB LIB(&LIBVAR))" is 
valid in a CL Program or procedure, but "SBMJOB CMD(&CMDVAR)" is not. 


Statement label. The statement label identifies the first of a series of QUAL or 
ELEM statements that further describe the qualified name or the mixed list 
being defined by this PARM statement. 


The following parameter types are for IBM-supplied commands only. 


Expression (*X). The parameter value is a character string, variable name, or 
numeric value. The value is passed as a numeric value if it contains only digits, 
a plus or minus sign, and/or a decimal point; otherwise, it is passed as a 
character string. 


Variable name (*VARNAME). The parameter value is a variable name, which is 
passed to the command processing program as a character string. The value is 
left-justified and is padded with blanks. A variable is a name that refers to an 
actual data value during processing. A variable name can be as long as 10 
alphanumeric characters (the first of which must be alphabetic) preceded by an 
ampersand (&); for example, &PARM. If the name of your variable does not 
follow the naming convention used on OS/400, you must enclose the name in 
apostrophes. 
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* Command (*CMD). The parameter value is a command. For example, the CL 
command IF has a parameter named THEN whose value must be another 


command. 


Length of Parameter Value 
You can also specify a length (LEN parameter) for parameter values of the 
following types. For parameter types of date or time, date is always 7 characters 
long and time is always 6 characters long. The following shows the maximum 
length for each parameter type and the default length for each parameter type for 
which you can specify a length. 


Data Type Maximum Length Default Length 
*DEC 24 (9 decimal positions) 15 (5 decimal positions) 
*LGL 1 1 

*CHAR 5000 32 

*NAME 256 10 

*SNAME 256 10 

*CNAME 256 10 

*GENERIC 256 10 

*HEX 256 1 

*X (256 24 9) (1 15 5) 
*VARNAME 11 1 

*CMDSTR 20K 256 

*PNAME 5000 32 


The maximum length that is shown here is the maximum allowed length for these 
parameter types when the command runs. However, the maximum length that is 
allowed for character constants in the command definition statements is 32 
characters. This restriction applies to the CONSTANT, DFT, VALUES, REL, 
RANGE, SPCVAL, and SNGVAL parameters. There are specific lengths for input 
fields available when prompting for a CL command. The input field lengths are 1 
through 12 characters and 17, 25, 32, 50, 80, 132, 256, and 512 characters. If a 
particular parameter has a length that is not allowed,the input field displays with 
the next larger field length. The prompter displays a 512-character input field for 
parameters that can be longer than 512 characters. 


Default Values 
If you are defining an optional parameter, you can define a value on the DFT 


parameter to be used if the user does not enter the parameter value on the 
command. This value is called a default value. The default value must meet all the 
value requirements for that parameter (such as type, length, and special values). If 
you do not specify a default value for an optional parameter, the following default 
values are used. 


Data Type Default Value 


*DEC 


*INT2 


*INT4 


*UINT2 


o;OoO;}o;}o;]o 


*UINT4 


*LGL ‘0’ 
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Data Type Default Value 
*CHAR Blanks 
*NAME Blanks 
*SNAME Blanks 
*CNAME Blanks 
*GENERIC Blanks 
*DATE Zeros (’FO’) 
*TIME Zeros (’FO’) 
*ZEROELEM 0 

*HEX Zeros (’00’) 
*NULL Null 
*CMDSTR Blanks 
*PNAME Blanks 


Example of Defining a Parameter 
The following example defines a parameter OETYPE for a command to call an 


order entry application. 
KWD(OETYPE) 


PARM 


TYPE (*CHAR) 


RSTD(*YES) 
VALUES (DAILY WEEKLY MONTHLY) 
PROMPT('Type of order entry:') 


MIN(1) 


The OETYPE parameter is required (MIN parameter is 1) and its value is restricted 
(RSTD parameter is *YES) to the values DAILY, WEEKLY, or MONTHLY. The 
PROMPT parameter contains the prompt text for the parameter. Since no LEN 
keyword is specified and TYPE(*CHAR) is defined, a length of 32 is the default. 


Data Type and Parameter Restrictions 


The following figure shows the valid combinations of parameters according to the 
parameter type. An X indicates that the combination is valid, a number refers to a 
restriction noted at the bottom of the table. 


LEN | RTNVAL 


CONSTANT 


RSTD 


DFT 


VALUES 


REL | RANGE 


SPCVAL 


SNGVAL 


*DEC 


Xx 


x< 


X 


*LGL 


*CHAR 


*NAME 


*SNAME 


*CNAME 


*PNAME 


*GENERIC 
*DATE 


*TIME 
*HEX 


x1 mK | KL mK] KX | mK] KX | mK | OX] 


x1 mK | XL mK] x | mK] KX | OK | KX] XX 


x 1K | KL mK] KX | mK] KL mK | KL KY] OX 


mK | mK | KL mK] | mK | OK | mK | OK 


x 1K | KX 1K] xX | KX | KX | OK | OX 
x1 K |X| mK] xX | mK] KX | OK] OX 


3 
3 
3 
3 
3 
3 
3 
3 
3 
3 
3 


ePlRelRedlelReilRele)lelResrRe|dr 


*ZEROELEM 


*INT2 
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LEN | RTNVAL | CONSTANT | RSTD | DFT | VALUES | REL |RANGE| SPCVAL | SNGVAL 

*INT4 x x x x Xx xX 3 1 
*UINT2 x x x xX 3 1 
*UINT4 xX xX xX x 3 1 
*CMDSTR xX xX x 

*NULL x 

STMT LABEL xX xX xX 

Notes: 


1. Valid only if the value for MAX is greater than 1. Also, To-values are ignored 
when CPP is a REXX procedure. Values passed as REXX procedure parameters 
are the values typed or the defaults for each parameter. 


2. Not valid when the command CPP is a REXX procedure. 
3. To-values are ignored when CPP is a REXX procedure. Values passed as REXX 


procedure parameters are the values typed or the default values for each 
parameter. 


MIN |MAX| ALWUNPRT | ALWVAR |PGM| DTAARA | FILE | FULL | EXPR | VARY 


*DEC 


*LGL 


*CHAR 


*NAME 


*SNAME 
*CNAME 


*PNAME 
*GENERIC 


mK | mK | mK | OK | OK | OX 
~ 1K | KL OK | KL OK | OX 
KK | KIL KL KL KL 
KK | KL mK] mK] OK 
ee ee eee 


KK] KL mK] KL KL KT mK] OX 


*DATE 


*TIME 


< 


x | KL mK | KX] KY] xT KL xX | KY] xX | xX 


*HEX 


*ZEROELEM 


*INT2 


*INT4 


*UINT2 


x< |< |< | xX 


*UINT4 


me 1K | K] K | OX 


*CMDSTR 


*NULL 
STMT LABEL 


KI] NTN | mK] OK] OK | OK | OK | OK LOK | OOK | OK | OK | OK] OK | OOK | OK | OK | OX 
mK |W] wy] «| mK] &K | KX | OK] mK | KX | OK LK] OK] KT OK] KX | OK | OX | OX 


Notes: 

1. Parameter is ignored when CPP is a REXX procedure. 

2. The value for MIN cannot exceed 1 for TYPE(*NULL). 

3. The value for MAX cannot exceed 1 for TYPE(*NULL) or TYPE(*CMDSTR). 
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4. The ALWVAR value is ignored for this type of parameter. CL variables are not 
allowed when the parameter type is *CMDSTR. 


PASSATR 


PASSVAL 


CASE 


LISTDSPL 


DSPINPUT 


*DEC 


1 


Xx 


3 


Xx 


Xx 


*LGL 


*CHAR 


*NAME 
*SNAME 


*CNAME 
*PNAME 


*GENERIC 


*DATE 


*TIME 


*HEX 


Pile tlRelelRedirRelrRelirRlrReldrR. 


x 
x 
x 
x 
xX 
x 
x 
xX 
x 
x 


x | mK | XK | xX | OX | OX | OX | OX | OX | OX 


x 
x 
x 
x 
x 
x 
x 
xX 
x 
x 


*ZEROELEM 


*INT2 


*INT4 


*UINT2 


*UINT4 


x |x| KX | xX 


*CMDSTR 


ePlReiRPlRe|]R 


3 
3 
3 
3 
3 
3 
3 
3 
3 
3 
3 
3 
3 
3 
3 
3 


x |X| K | KX | OX 


x) xX |X| xX | xX 


*NULL 


STMT LABEL 


CHOICE 


CHOICEPGM 


PMTCTL 


PMTCTLPGM 


PROMPT 


INLPMTLEN 


*DEC 


Xx 


Xx 


Xx 


Xx 


*LGL 


*CHAR 


*NAME 


*SNAME 


*CNAME 


*PNAME 


*GENERIC 


ee er a 


*DATE 


*TIME 


*HEX 


xX] XK |X| KL x | OK | XL OK | KX] OX 


x) mK | KL mK] KL mK] KL mK] KY] xX 


KL mK | OK | mK] OK | mK | OK] mK | OK] OX 


x) mK | KL mK] KL mK] KL mK | KY] 


mx |X | mK | OK | KX | OK | KT OX | KT OK | OX 


*ZEROELEM 


*INT2 
*INT4 


*UINT2 


*UINT4 


*CMDSTR 


x | KX | K | KX] OX 


x) xX |X| xX |X 


x | «|X| XX | OX 


x) xX |X| xX |X 


x | KX | KX | KT OX 


Chapter 9. Defining Commands 


295 


CHOICE CHOICEPGM PMTCTL PMTCTLPGM PROMPT [NLPMTLEN 
*NULL 
STMT LABEL xX xX X xX x x 
Notes: 
1. Parameter is ignored when CPP is a REXX procedure. 
2. PASSVAL passes a keyword with no blanks or other characters between 
parentheses when CPP is a REXX procedure. 
3. Case (*MIXED) is allowed only with type *CHAR and *PNAME. 
4. You can use INLPMTLEN(*PWD) only with types *CHAR, *NAME, *SNAME, 
*CNAME, and *PNAME. 
The next figure shows the valid parameter combinations and restrictions for the 
PARM, ELEM, and QUAL statements. For example, the intersection of the row for 
LEN and the column for DFT are blank; therefore, there are no restrictions and 
combination of LEN(XX) and DFT(XX) is valid. However, the intersection of the 
row for DFT and the column for CONSTANT contains a 4 which refers to a note at 
the bottom of the table describing the restriction. 
LEN | RTNVAL | CONSTANT | RSTD | DFT) VALUES | REL |RANGE| SPCVAL | SNGVAL 
LEN 
RINVAL 1 1 1 1 1 1 1 
CONSTANT 1 4 16 
RSTD 1 7 9 7 7 
DFT 1 4 
VALUES 1 7 
REL 1 9 
RANGE 1 9 9 
SPCVAL 1 7 
SNGVAL 1 21 Vi, 
MIN 8 
MAX 2 2 10 
ALWUNPRT 
ALWVAR 12 
PGM 1 
DTAARA 1 
FILE 1 
FULL 1 
EXPR 1 5 
VARY 3 
PASSATR ) 
PASSVAL 13 
CASE 
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LEN | RTNVAL | CONSTANT | RSTD | DFT | VALUES | REL |RANGE| SPCVAL | SNGVAL 


LISTDSPL 


CHOICE 14 


CHOICEPGM 


PMTCTL 15 


PMTCTLPGM 15 


PROMPT 6 


INLPMTLEN 17 17 17 


Notes: 


1. The RTNVAL parameter cannot be used with any of the following parameters: 
CONSTANT, RSTD, DFT, VALUES, REL, RANGE, SPCVAL, SNGVAL, PGM, 
DTAARA, FILE, FULL, or EXPR. The RTNVAL parameter cannot be used on 
any command using a REXX procedure as a CPP. 


2. A MAX value greater than 1 is not allowed. 


3. If PASSATR(*YES) and RTNVAL(*YES) are specified, VARY(*YES) must also be 
specified. If RTNVAL(*YES) and VARY(*YES) are specified, you must use 
either *INT2 or *INT4. Combinations of *INT2 and *INT4 are not valid. 


4. The CONSTANT and DFT parameters are mutually exclusive. 

5. The EXPR(*YES) and CONSTANT parameters are mutually exclusive. 
6. The PROMPT parameter is not allowed. 

7 


. If the RSTD parameter is specified, one of the following parameters must also 
be specified: VALUES, SPCVAL, or SNGVAL. 


8. The MIN value must be 0. 
9. The REL, RANGE, and RSTD(*YES) parameters are mutually exclusive. 

10. Either the MAX value must be greater than 1 or the parameter type must be a 
statement label, or both. 

11. The parameter may not refer to a parameter defined with the parameter 
PASSVAL(*NULL). A range between parameters is not valid on a PARM 
statement defined with PASSVAL(*NULL). 

12. If RTNVAL(*YES) is specified, ALWVAR(*NO) cannot be specified. 

13. PASSVAL(*NULL) is not allowed with RTNVAL(*YES) or a value greater than 
0 for MIN. 

14. The CHOICE and CONSTANT parameters are mutually exclusive. 

15. CONSTANT is mutually exclusive with the PMTCTL and PMTCTLPGM 
parameters. 

16. The CONSTANT parameter cannot be defined on the ELEM/QUAL statement 
if a SNGVAL parameter is defined on the PARM statement. 

17. You cannot use the INLPMTLEN parameter with CONSTANT. You must 
specify INLPMTLEN(*CALC) or use it as the default if you have specified 
FULL(*YES), RTNVAL(*YES), or RSTD(*YES). 


MIN | MAX | ALWUNPRT | ALWVAR | PGM | DTAARA | FILE | FULL | EXPR | VARY 


LEN 


RTNVAL 2 8 1 1 1 1 1 3 


CONSTANT 2 4 
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MIN 


MAX} ALWUNPRT | ALWVAR | PGM | DTAARA | FILE | FULL | EXPR | VARY 


ALWUNPRT 


ALWVAR 


PGM 


DTAARA 


VARY 


PASSATR 


PASSVAL 


10 


CASE 


LISTDSPL 


CHOICE 


CHOICEPGM 


PMTCTL 


11 


PMTCTLPGM 


PROMPT 


INLPMTLEN 


12 


Notes: 


1. 


o 


The RTNVAL parameter cannot be used with any of the following parameters: 
CONSTANT, RSTD, DFT, VALUES, REL, RANGE, SPCVAL, SNGVAL, PGM, 
DTAARA, FILE, FULL, or EXPR. The RTNVAL parameter cannot be used on 
any command using a REXX procedure as a CPP. 

A MAX value greater than 1 is not allowed. 

If PASSATR(*YES) and RTNVAL(*YES) are specified, VARY(*YES) must also be 
specified. If RTNVAL(*YES) and VARY(*YES) are specified, you must use 
either *INT2 or *INT4. Combinations of *INT2 and *INT4 are not valid. 

The EXPR(*YES) and CONSTANT parameters are mutually exclusive. 

The MIN value must be 0. 


The value specified for the MIN parameter must not exceed the value 
specified for the MAX parameter. 
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7. Either the MAX value must be greater than 1 or the parameter type must be a 


statement label, or both. 


8. If RTNVAL(*YES) is specified, ALWVAR(*NO) cannot be specified. 
9. PGM(*YES), DTAARA(*YES), and a value other than *NO for the FILE 


parameters are mutually exclusive. 


10. PASSVAL(*NULL) is not allowed with RTNVAL(*YES) or a value greater than 


0 for MIN. 


11. PMTCTL is not allowed with a value greater than 0 for MIN. 
12. You must specify INLPMTLEN(*CALC) or use it as the default if you 


specified FULL“YES), RTNVAL(*YES), or RSTD(*YES). 


PASSATR PASSVAL CASE 


LISTDSPL 


DSPINPUT 


LEN 


RTNVAL 


CONSTANT 


RSTD 


DFT 


VALUES 


REL 
RANGE 


SPCVAL 


SNGVAL 
MIN 


MAX 


ALWUNPRT 


ALWVAR 


PGM 


DTAARA 


FILE 


FULL 


EXPR 


VARY 


PASSATR 


PASSVAL 
CASE 


10 


LISTDSPL 


11 


CHOICE 


CHOICEPGM 


PMTCTL 
PMTCTLPGM 


PROMPT 


INLPMTLEN 
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CHOICE CHOICEPGM PMTCTL PMTCTLPGM PROMPT INLPMTLEN 
LEN 
RTNVAL 12 
CONSTANT 7 7 2 12 
RSTD 12 
DFT 
ALWUNPRT 
ALWVAR 
12 


LISTDSPL 


CHOICE 


CHOICEPGM 


PMTCTL 
PMTCTLPGM 


PROMPT 


INLPMTLEN 


Notes: 


If PASSATR(*YES) and RTNVAL(*YES) are specified, VARY(*YES) must also be 
specified. If RTNVAL(*YES) and VARY(*YES) are specified, you must use 
either *INT2 or *INT4. Combinations of *INT2 and *INT4 are not valid. 


The PROMPT parameter is not allowed. 


The parameter may not refer to a parameter defined with the parameter 
PASSVAL(*NULL). A range between parameters is not valid on a PARM 
statement defined with PASSVAL(*NULL). 


PASSVAL(*NULL) is not allowed with RTNVAL(*YES) or a value greater than 


A 


O for MIN. 
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5. The CHOICE and CONSTANT parameters are mutually exclusive. 
6. CHOICE(*PGM) requires a name for CHOICEPGM. 
7. CONSTANT is mutually exclusive with the PMTCTL and PMTCTLPGM 
parameters. 
8. PMTCTL is not allowed with a value greater than 0 for MIN. 
9. CONSTANT is mutually exclusive with DSPINPUT(*NO) and 
DSPINPUT(*PROMPT). 
10. The CASE parameter is valid only on PARM and ELEM statements. CASE is 
not valid on the QUAL statement. 
11. The LISTDSPL parameter is valid only on the PARM statement. 
12. You cannot use the INLPMTLEN parameter with CONSTANT. You must 
specify INLPMTLEN(*CALC) or use it as the default if you specified 
FULL(*YES), RTNVAL(*YES), or RSTD(*YES). 


Defining Lists for Parameters 


You can define a parameter to accept a list of values instead of just a single value. 

You can define the following types of lists: 

* A simple list, which allows one or more values of the same type to be specified 
for a parameter 

* A mixed list, which allows a set of separately defined values to be specified for 
a parameter 


* A list within a list, which allows a list to be specified more than once for a 
parameter or which allows a list to be specified for a value within a mixed list 


The following sample command source illustrates the different types of lists: 
CMD PROMPT('Example of lists command') 


/* THE FOLLOWING PARAMETER IS A SIMPLE LIST. IT WILL ACCEPT UP TO */ 
/* 5 NAMES. x/ 
PARM KWD(SIMPLST) TYPE(*NAME) LEN(10) DFT(*ALL) + 
SPCVAL((*ALL)) MAX(5) PROMPT('Simple list + 
of up to 5 names') 


/* THE FOLLOWING PARAMETER IS A MIXED LIST OF 3 VALUES, EACH OF A */ 
/* DIFFERENT TYPE AND/OR LENGTH. EACH ELEMENT MAY NOT BE REPEATED. +/ 


PARM KWD(MXDLST) TYPE(MLSPEC) PROMPT('This is a + 
mixed list of 3 val') 
MLSPEC: ELEM TYPE(*CHAR) LEN(4) PROMPT('Elem 1 of 3') 
ELEM TYPE(*DEC) LEN(3 0) PROMPT('Second of three') 
ELEM TYPE(*CHAR) LEN(10) PROMPT('Last of three + 
elements ') 


/* THE FOLLOWING PARAMETER IS A LIST WITHIN A LIST. IT CONTAINS A */ 
/* LIST OF UP TO 2 ELEMENTS, WHICH MAY BE REPEATED UP TO 3 TIMES. = */ 


PARM KWD(LWITHINL1) TYPE(LWLSPECA) MAX(3) + 
PROMPT ('Repeatable list of 2 elements') 
LWLSPECA: ELEM TYPE(*CHAR) LEN(10) PROMPT('1lst part of + 
repeatable list') 
ELEM TYPE(*DEC) LEN(5 0) PROMPT('2nd part of + 


repeatable list') 


/* THE FOLLOWING PARAMETER IS A LIST WITHIN A LIST. IT CONTAINS A */ 
/* LIST OF UP TO 2 ELEMENTS, THE FIRST OF WHICH MAY BE REPEATED x/ 
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/* UP TO 3 TIMES. */ 


PARM KWD(LWITHINL2) TYPE(LWLSPECB) MAX(1) + 
PROMPT('Repeated simple within mixed') 
LWLSPECB: ELEM TYPE(*CHAR) LEN(10) MAX(3) PROMPT('Simple + 
list within a list') 
ELEM TYPE(*DEC) LEN(5 0) PROMPT('Single parm + 


within a list') 


The following display shows the prompt for the preceding sample command: 


Pe 
Example of lists command (LSTEXAMPLE) _ 


Type choices, press Enter. 


Simple list of up to 5 names . . SIMPLST *ALL 
+ for more values 
This is a mixed list of 3 val MXDLST 
emt of3) ce eerrsers es 2 eee cote 
Second of three «. <5. <. % « << 
Last of three elements... . 
Repeatable list of 2 elements LWITHINL1 
lst part of repeatable list 
2nd part of repeatable list 
+ for more values 
Repeatable simple within mixed LWITHINL2 
Simple list within a list 
+ for more values 
Single parm within a list 


Bottom 
F3=Exit F4=List  F5=Refresh  F12=Cancel F13=Prompter help 
F24=More keys 
Ne 


Defining a Simple List 


A simple list can accept one or more values of the type specified by the parameter. 
For example, if the parameter is for the user name, a simple list means that more 
than one user name can be specified on that parameter. 


USER(JONES SMITH MILLER) 


If a parameter’s value is a simple list, you specify the maximum number of 
elements the list can accept using the MAX parameter on the PARM statement. For 
a simple list, no command definition statements other than the PARM statement 
need be specified. 


The following example defines a parameter USER for which the display station 
user can specify up to five user names (a simple list). 


PARM KWD(USER) TYPE(*NAME) LEN(10) MIN(O) MAX(5) + 
SPCVAL(*ALL) DFT(*ALL) 


The parameter is an optional parameter as specified by MIN(0) and the default 
value is *ALL as specified by DFT(*ALL). 


When the elements in a simple list are passed to the command processing 
program, the format varies depending on whether you are using CL or HLL, or 
REXX. The following section describes how the elements used in the previous 
example are passed_using CL and HLL. For an explanation of the differences when 
using REXX, see 
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Using CL or HLL for Simple Lists 


When the command is run using CL or HLL, the elements in a simple list are 


passed to the command processing program in the following format. 


Number 
of Values Value Value Value Value ... 
Passed 

RBAFN509-0 


The number of values passed is specified by a binary value that is two characters 


long. This number indicates how many values were actually entered (are being 

passed), not how many can be specified. The values are passed by the type of 
arameter just as a value of a single parameter is passed (as described under 

). For example, if two user names (BJONES and TBROWN) are 


betaine Panes 


specified for the USER parameter, the following is passed. 


0002 


BJONES 


TBROWN 


RBAFN5S10-0 


The user names are passed as 10-character values that are left-adjusted and padded 


with blanks. 


When a simple list is passed, only the number of elements specified on the 


command are passed. The storage immediately following the last element passed is 
not part of the list and must not be referred to as part of the list. Therefore, when 

the command processing program (CPP) processes a simple list, it uses the number 
of elements passed to determine how many elements can be processed. 


shows an example of a CL procedure using the binary 
built-in function to process a simple list. 
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PGM PARM (...&USER..) 


/* Declare space for a simple list of up to five */ 
/* 10-character values to be received */ 
DCL VAR(&USER) TYPE(*CHAR) LEN(52) 


DCL VAR(&CT) TYPE(*DEC) LEN(3 0) 
DCL VAR(&USER1) TYPE(*CHAR) LEN(10) 
DCL VAR(&USER2) TYPE(*CHAR) LEN(10) 
DCL VAR(&USER3) TYPE(*CHAR) LEN(10) 
DCL VAR(&USER4) TYPE(*CHAR) LEN(10) 
DCL VAR(&USER5) TYPE(*CHAR) LEN(10) 


CHGVAR VAR(&CT) VALUE(%BINARY(&USER 1 2)) 


IF 


(&CT > ©) THEN(CHGVAR &USER1 %SST(&USER 3 10)) 
IF (&CT > 1) THEN(CHGVAR &USER2 %SST(&USER 13 10)) 
IF (&CT > 2) THEN(CHGVAR &USER3 %SST(&USER 23 10)) 
IF (&CT > 3) THEN(CHGVAR &USER4 %SST(&USER 33 10)) 
IF (&CT > 4) THEN(CHGVAR &USER5 %SST(&USER 43 10)) 
IF (&CT > 5) THEN(DO) 
/* If CT is greater than 5, the values passed x/ 
/* is greater than the program expects, and error */ 
/* logic should be performed */ 
ENDDO 
ELSE DO 


/* The correct number of values are passed */ 
/* and the program can continue processing */ 


ENDDO 
ENDPGM 


Figure 13. Simple List Example 


This same technique can be used to process other lists in a CL procedure or 
program. 


For a simple list, a single value such as *ALL or *NONE can be entered on the 
command instead of the list. Single values are passed as an individual value. 
Similarly, if no values are specified for a parameter, the default value, if any is 
defined, is passed as the only value in the list. For example, if the default value 
*ALL is used for the USER parameter, the following is passed. 


0001 *ALL 


RBAFN511-0 


*ALL is passed as a 10-character value that is left-adjusted and padded with 
blanks. 
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If no default value is defined for an optional simple list parameter, the following is 
passed: 


0000 


RBAFN512-0 


Using REXX for Simple Lists 
When the same command is run, the elements in a simple list are passed to the 
REXX procedure in the argument string in the following format: 


. USER(valuel value2 ... valueN)... 
where valueN is the last value in the simple list. 


For example, if two user names (BJONES and TBROWN) are specified for the 
USER parameter, the following is passed: 


. USER(BJONES TBROWN) .. . 
When a simple list is passed, only the number of elements specified on the 


command are passed. Therefore, when the CPP processes a simple list, it uses the 
number of elements passed to determine how many elements can be processed. 


The REXX as in Figure 14] produces the same result as the CL procedure in 


PARSE ARG . 'USER(' user ')' . 


CT = WORDS (user) 


IF CT > @ THEN userl = WORD(user,1) else userl = ' 
IF CT > 1 THEN user2 = WORD(user,2) else user2 = ' 
IF CT > 2 THEN user3 = WORD(user,3) else user3 = ' 
IF CT > 3 THEN user4 = WORD(user,4) else user4 = ' 
IF CT > 4 THEN user5 = WORD(user,5) else userd = ' 
IF CT > 5 THEN 

DO 


/* If CT is greater than 5, the values passed 
is greater than the program expects, and error 
logic should be performed */ 


END 
ELSE 
DO 
/* The correct number of values are passed 
and the program can continue processing */ 
END 
EXIT 


Figure 14. REXX Simple List Example 


This same procedure can be used to process other lists in a REXX program. 


For a simple list, a single value such as *ALL or *NONE can be entered on the 
command instead of the list. Single values are passed as an individual value. 
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Similarly, if no values are specified for a parameter, the default value, if any is 
defined, is passed as the only value in the list. For example, if the default value 
*ALL is used for the USER parameter, the following is passed: 


. USER(*ALL) . . . 


If no default value is defined for an optional simple list parameter, the following is 
passed: 


. . USER() . 


For more information about REXX procedures, see the IREXX /400 Programmer's 
Gand and the REXX/GOO Refereed 


Defining a Mixed List 


A mixed list accepts a set of separately defined values that usually have different 
meanings, are of different types, and are in a fixed position in the list. For example, 
LOG(4 0 *SECLVL) could specify a mixed list. The first value, 4, identifies the 
message level to be logged; the second value, 0, is the lowest message severity to 
be logged. The third value, *SECLVL, specifies the amount of information to be 
logged (both first- and second-level messages). If a parameter’s value is a mixed 
list, the elements of the list must be defined separately using an Element (ELEM) 
statement for each element. 


The TYPE parameter on the associated PARM statement must have a label that 
refers to the first ELEM statement for the list. 


PARM KWD(LOG) = TYPE(LOGLST) ... 


LOGLST: ELEM  TYPE(*INT2) 
ELEM —- TYPE(*INT2) aa 
ELEM TYPE(*CHAR) LEN(7) 


The first ELEM statement is the only ELEM statement that can have a label. 
Specify the ELEM statements in the order in which the elements occur in the list. 


Note that when the MAX parameter has a value greater than 1 on the PARM 
statement, and the TYPE parameter refers to ELEM statements, the parameter 
being defined is a list within a list. 


Parameters that you can specify on the ELEM statement include TYPE, LEN, 
CONSTANT, RSTD, DFT, VALUES, REL, RANGE, SPCVAL, SNGVAL, MIN, MAX, 
ALWUNPRT, ALWVAR, PGM, DTAARA, FILE, FULL, EXPR, VARY, PASSATR, 
CHOICE, CHOICEPGM, and PROMPT. 


In the following example, a parameter CMPVAL is defined for which the display 
station user can specify a comparison value and a starting position for the 
comparison (a mixed list). 
PARM KWD(CMPVAL) TYPE(CMP) SNGVAL(*ANY) DFT(*ANY) + 
MIN(Q) 
CMP: ELEM TYPE(*CHAR) LEN(80) MIN(1) 
ELEM TYPE(*DEC) LEN(2 @) RANGE(1 80) DFT(1) 


When the elements in a mixed list are passed to the command processing program, 
the format varies depending on whether you are using CL or HLL, or REXX. The 
following section describes how the elements used in the previous example are 
passed _using CL and HLL. For an explanation of the differences when using REXX, 
see 8 
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Using CL or HLL for Mixed Lists 
When a command is run using CL or HLL, the elements in a mixed list are passed 
to the command processing program in the following format: 


ola of Value of Value of Value of 
Values in the reer 
: ; Element 1 Element 2 Element n 
Mixed List 
RBAFN513-0 


The number of values in the mixed list is passed as a binary value of length 2. This 
value always indicates how many values have been defined for the mixed list, not 
how many were actually entered on the command. This value may be 1 if the 
SNGVAL parameter is entered or is passed as the default value. If the user does 
not enter a value for an element, a default value is passed. The elements are 
passed by their types just as single parameter values are passed (as described 

)). For example, if, in the previous 
example the user enters a comparison value of QCMDI for the CMPVAL 
parameter, but does not enter a value for the starting position, whose default value 
is 1, the following is passed. 


0002 QCMDI il 
RBAFN514-0 


The data QCMDI is passed as an 80-character value that is left-adjusted and 
padded with blanks. The number of elements is sent as a binary value of length 2. 


When the display station user enters a single value or when a single value is the 
default for a mixed list, the value is passed as the first element in the list. For 
example, if the display station user enters *ANY as a single value for the 
parameter, the following is passed. 


0001 *ANY 


RBAFN515-0 


*ANY is passed as an 80-character value that is left-adjusted and padded with 
blanks. 


Mixed lists can be processed in CL programs. Unlike simple lists, the binary value 
does not need to be tested to determine how many values are in the list because 
this value is always the same for a given mixed list unless the SNGVAL parameter 
was passed to the command processing program. In this case, the value is 1. If the 
command is entered with a single value for the parameter, only that one value is 
passed. To process the mixed list in a CL procedure, you must use the substring 
built-in function (see 


In one case, only a binary value of 0000 is passed as the number of values for a 
mixed list. If no default value is defined on the PARM statement for an optional 
parameter and the first value of the list is required (MIN(1)), then the parameter 
itself is not required; but if any element is specified the first element is required. In 
this case, if the command is entered without specifying a value for the parameter, 
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the following is passed. 


0000 


RBAFN512-0 


An example of such a parameter is: 


PARM KWD(KWD1) TYPE(E1) MIN(Q) 
El: ELEM TYPE(*CHAR) LEN(10) MIN(1) 
ELEM TYPE(*CHAR) LEN(2) MIN(0) 


If this parameter were to be processed by a CL procedure, the parameter value 
could be received into a 14-character CL variable. The first 2 characters could be 
compared to either of the following: 

* a 2-character variable initialized to hex 0000 using the %SUBSTRING function. 
* a decimal 0 using the %BINARY built-in function. 


Using REXX for Mixed Lists 
When a command is run using REXX, the elements in a mixed list are passed to 
the command processing program in the following format: 


. . CMPVAL(valuel value2 .. .valueN) ... 
where valueN is the last value in the mixed list. 


If the user does not enter a value for an element, a default value is passed. For 
example, if in the previous example, the user enters a comparison value of QCMDI 
for the CMPVAL parameter, but does not enter a value for the starting position, 
whose default value is 1, the following is passed: 


. . CMPVAL(QCMDI 1) 
Note that trailing blanks are not passed with REXX values. 


When a display station user enters a single value or when a single value is the 
default for a mixed list, the value is passed as the first element in the list. For 
example, if the display station user enters *ANY as a single value for the 
parameter, the following is passed: 


. « CMPVAL(*ANY) . . 
Again note that trailing blanks are not passed with REXX values. 


If no default value is defined on the PARM statement for an optional parameter 
and the first value of the list is required (MIN(1)), then the parameter itself is not 
required. But if any element is specified, the first element is required. In this case, 
if the command is entered without specifying a value for the parameter, the 
following is passed: 

. . CMPVAL() .. . 


Defining Lists within Lists 
A list within a list can be: 
* A list that can be specified more than once for a parameter (simple or mixed list) 
* A list that can be specified for a value within a mixed list 


The following is an example of lists within a list. 
STMT((START RESPND) (ADDDSP CONFRM) ) 
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The outside set of parentheses enclose the list that can be specified for the 
parameter (the outer list) while each set of inner parentheses encloses a list within 
a list (an inner list). 


In the following example, a mixed list is defined within a simple list. A mixed list 
is specified, and the MAX value on the PARM statement is greater than 1; 
therefore, the mixed list can be specified up to the number of times specified on 
the MAX parameter. 

PARM KWD(PARM1) TYPE(LIST1) MAX(5) 


LIST1: ELEM TYPE(*CHAR) LEN(10) 
ELEM TYPE(*DEC) LEN(3 0) 


In this example, the two elements can be specified up to five times. When a value 
is entered for this parameter, it could appear as follows: 


PARM1((VAL1 1.0) (VAR2 2.0) (VAR3 3.0)) 


In the following example, a simple list is specified as a value in a mixed list. In 
this example, the MAX value on the ELEM statement is greater than 1; therefore, 
the element can be repeated up to the number of times specified on the MAX 
parameter. 

PARM KWD(PARM2) TYPE(LIST2) 


LIST2: ELEM TYPE(*CHAR) LEN(10) MAX(5) 
ELEM TYPE(*DEC) LEN(3 0) 


In this example, the first element can be specified up to five times, but the second 
element can be specified only once. When a value is entered for this parameter, it 
could appear as follows. 


PARM2((NAME1 NAME2 NAME3) 123.0) 


When lists within lists are passed to the command processing program, the format 
varies depending on whether you are using CL or HLL, or REXX. The following 
section describes how elements are passed_using CL and HLL. For an explanation 


of the differences when using REXX, see (‘Using REXX for Lists within Lists” onl 


Using CL or HLL for Lists within Lists 
When a command is run using CL or HLL, a list within a list is passed to the 
command processing program in the following format: 


Number | Displace- | Displace- Displace- 

Parameter 
of ment to ment to sate ment to fieka 
Lists List 1 List 2 List n 


RBAFN5S34-0 


The number of lists is passed as a binary value of length 2. Following the number 
of lists, the displacement to the lists is passed (not the values that were entered in 
the lists). Each displacement is passed as a binary value of length 2 or length 4 
depending on the value of the LISTDSPL parameter. 


The following example shows a definition for a parameter KWD2 (which is a 
mixed list within a simple list) how the parameter can be specified by the display 
station user, and what is passed. The parameter definition is: 
PARM  KWD(KWD2) = TYPE(LIST) MAX(20) MIN(O) + 
DFT(*NONE) SNGVAL(*NONE) LISTDSPL(*INT2) 
LIST: ELEM  TYPE(*CHAR) LEN(10) MIN(1) /*From valuex/ 
ELEM  TYPE(*CHAR) LEN(5) MIN(0) /*To valuex/ 
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The display station user enters the KWD2 parameter as: 


KWD2((A B)) 


The following is passed to the command processing program: 


0001 


0004 0002 | A 


Start of Inner List 


Number of Lists 


Passed as 5 Characters 


Passed as 10 Characters 


Number of Values Specified in Inner List 


Displacment to Inner List (LISTDSPL (*INT2) 


RBAFN516-0 
If the display station user enters the following instead: 
KWD2((A B) (C D)) 
the following is passed to the command processing program: 
Number of Values 
Specified in Inner List 
0002| 0023 | 0006 | 0002 | C D 0002 A B 
Passed Passed Passed 
as 10 as 10 as 5 
Characters Characters Characters 
Start of Start of First List 
Second List 
Passed as 5 Characters 
Displacement to Second List Entered by User (C D) 
Displacement to First List Entered by User (A B) 
Number of Lists RBAFNS17.0 


Lists within a list are passed to the command processing program in the order n 
(the last one entered by the display station user) to 1 (the first one entered by the 
display station user). The displacements, however, are passed from 1 to n. 


The following is a more complex example of lists within lists. The parameter 


definition is: 


PARM 
LIST3: ELEM 
ELEM 
ELEM 
LIST4: ELEM 
ELEM 
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KWD(PARM1) TYPE(LIST3) MAX(25) 


TYPE(LIST4) 
TYPE(*CHAR) LEN(3) 
TYPE(*NAME) LEN(2) 
TYPE(*DEC) LEN(7 2) 
TYPE(*TIME) 


MAX (5) 


If the display station user enters the PARM1 parameter as: 


PARM1(((11.1 120900) A (Al A2)) ((-22.2 131500) B (Bl B2))) 


the following is passed to the command processing program: 


0002 | 


0021 | 0006 


Number of lists 


Displacement to second list 


Displacement to first list 


4. 


0003 "0016 | B | 0009 | 0002 | at | 82 | 0002 22.2 | 131500 


Second value passed as 
character string of length 6 
First value passed as packed decimal 
Number of values in mixed list (LIST4) 
Simple list values passed as two characters each 
Number of values in simple list 
Displacement from beginning of this list to simple list 
Second element (LIST3) passed as three characters 
Displacement from beginning of this list to inner list (LIST4) 
Number of elements specified in inner list (LISTS) 


~” 


120900 


0003 “oo18 c | 0009 “0002 rn ne "0002 | 11.1 


Second value passed as 
character string of length 6 


First value passed as packed decimal 
Number of values in mixed list (LIST4) 

Simple list values passed as two characters each 

Number of values in simple list 
Displacement from beginning of this list to simple list 

Second element (LIST3) passed as three characters 
Displacement from beginning of this list to inner list (LIST4) 
Number of elements specified in inner list (LISTS) 


Using REXX for Lists within Lists 


When a command is run using REXX, a list within a list is passed to the command 


processing program just as the values are entered for the parameters. Trailing 
blanks are not passed. 


The following example shows a definition for a parameter KWD2, which is a 


mixed list within a simple list, how the parameter can be specified by the display 


station user, and what is passed. The parameter definition is: 


PARM  KWD(KWD2) | TYPE(LIST) MAX(20) MIN(O) + 
DFT(*NONE) SNGVAL(*NONE) 
LIST: ELEM  TYPE(*CHAR) LEN(10) MIN(1) /*From valuex/ 
ELEM  TYPE(*CHAR) LEN(5) MIN(0) /*To valuex/ 


The display station user enters the KWD2 parameter as: 
KWD2((A B)) 
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RV2W506-1 


The following is passed to the command processing program: 
KWD2(A B) 


If the display station user enters the following instead: 
KWD2((A B) (C D)) 


The following is passed to the command processing program: 
KWD2((A B) (C D)) 


The following is a more complex example of lists within lists. The parameter 
definition is: 
PARM KWD(PARM1) TYPE(LIST3) MAX(25) 
LIST3: ELEM TYPE(LIST4) 
ELEM TYPE(*CHAR) LEN(3) 
ELEM TYPE(*NAME) LEN(2) MAX(5) 
LIST4: ELEM TYPE(*DEC) LEN(7 2) 
ELEM TYPE(*TIME) 


The display station user enters the PARM1 parameter as: 
PARM1(((11.1 12D900) A (Al A2)) ((-22.2 131500) B (B1 B2))) 


The following is passed to the command processing program: 
PARM1(((11.1 12D900) A (Al A2)) ((-22.2 131500) B (Bl B2))) 


Defining a Qualified Name 


A qualified name is the name of an object preceded by the name of the library in 
which the object is stored. If a parameter value or list item is a qualified name, you 
must define the name separately using Qualifier (QUAL) statements. Each part of 
the qualified name must be defined with a QUAL statement. The parts of a 
qualified name must be described in the order in which they occur in the qualified 
name. You must specify *NAME or *GENERIC in the first QUAL statement. The 
associated PARM or ELEM statement must identify the label that refers to the first 
QUAL statement for the qualified name. 


The following command definition statements define the most common qualified 
name. A qualified object consists of the library name which contains an object 
followed by the name of the object itself. The QUAL statements must appear in the 
order in which they are to occur in the qualified name. 


PARM KWD(NAME) TYPE(NAME1) SNGVAL(*NONE)... 


—> NAME1: QUAL TYPE (*NAME) 


QUAL TYPE(*NAME) 
RBAFN518-0 


Many of the parameters that can be specified for the QUAL statement are the same 
as those described for the PARM statement (see “De 

). However, only the following values can be specified for the TYPE 
parameter: 


° *NAME 

°° *GENERIC 
° *CHAR 

° *INT2 
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° *INT4 


When a qualified name is passed to the command processing program, the format 
varies depending on whether you are using CL or HLL, or REXX. The following 
section describes how qualified names are passed using CL and HLL. For an 


explanation of the differences when using REXX, see g 


Using CL or HLL for a Qualified Name 
A qualified name is passed to the command processing program in the following 
format when using CL or HLL: 


Value Value 

of of 

Qualifier 1) Qualifier 2 
RBAFN519-0 


For example, if the display station user enters NAME(USER/A) for the previously 
defined QUAL statements, the name is passed to the command processing 
program as follows: 


A USER 
—10 Bytes 10 Bytes— 
RBAFN520-0 


Qualifiers are passed to the command processing program consecutively by their 
pes and length just as single parameter values are passed (as described under 
2 }). The separator characters (/) are not passed. 
This applies fegardlese of whether a single parameter, an element of a mixed list, 
or a simple list of qualified names is passed. 


If the display station user enters a single value for a qualified name, the length of 
the value passed is the total of the length of the parts of the qualified name. For 
example, if you define a qualified name with two values each of length 10, and if 
the display station user enters a single value, the single value passed is 
left-adjusted and padded to the right with blanks so that a total of 20 characters is 
passed. If the display station user enters *NONE as the single value, the following 
20-character value is passed: 


*NONE 


RBAFN521-0 


Qualified names can be processed in CL programs using the Substring built-in 
function as shown in the following example. 


The substring built-in function (YSUBSTRING or %SST) is used to separate the 
qualified name into two values. 


PGM PARM(&QLFDNAM) 

DCL &QLFDNAM TYPE(*CHAR) LEN(20) 

DCL &0BJ TYPE(*CHAR) LEN(10) 

DCL &LIB TYPE(*CHAR) LEN(10) 

CHGVAR &0BJ %SUBSTRING(&QLFDNAM 1 10) /* First 10 */ 
CHGVAR &LIB %SST(&QLFDNAM 11 10) /* Second 10 / 
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ENDPGM 


You can then specify the qualified name in the proper CL syntax. For example, 
OBJ (&LIB/&0BJ). 


You can also separate the qualified name into two values using the following 
method: 


PGM PARM(&QLFDNAM) 
DCL &QLFDNAM TYPE(*CHAR) LEN(20) 
CHKOBJ (%SST(&QLFDNAM 11 10)/%SST(&QLFDNAM 1 10)) *PGM 


ENDPGM 


A simple list of qualified names is passed to the command processing program in 
the following format: 


aerate Value 1 Value 1 Value 2 Value 2 
ie ifie Qualifier 1 | Qualifier 2 | Qualifier 1 | Qualifier 2 
ames 


RBAFN522-0 
For example, assume that MAX(3) were added as follows to the PARM statement 
for the NAME parameter. 


PARM KWD(NAME) TYPE(NAME1) SNGVAL(*NONE) MAX (3) 
NAMEL: QUAL TYPE(*NAME) 
QUAL TYPE(*NAME) 


If the display station user enters the following: 
NAME(QGPL/A USER/B) 


then the name parameter would be passed to the command processing program as 
follows. 


0002 A QGPL B USER 
L10 Bytes 10 Bytes— (10 Bytes — | 10 Bytes— 
RBAFN523-0 


If the display station user enters the single value NAME(*NONE), the name 
parameter is passed as follows. 


0001 *NONE 


i220 Bytes 
RBAFN524-0 


Using REXX for a Qualified Name 


When a command is run using REXX, a qualified name is passed to the command 
processing program just as the value is entered for the parameter. Trailing blanks 
are not passed. 


For example, if a display station user enters the following for the QUAL statements 
defined previously in this section: 


314 0S/400 CL Programming V5R2 


NAME (USER/A) 


the qualified name is passed to the command processing program in the following 
format: 


NAME (USER/A) 


Qualifiers are passed to the command processing program consecutively by their 
pes and length just as single parameter values are passed (as described under 


If the display station user enters *NONE as the single value, the following 
20-character value is passed: 


NAME (*NONE) 


The following example shows how a display station user would enter a simple list 
of qualified names: 


NAME(QGPL/A USER/B) 


Using REXX, the name parameter would be passed to the command processing 
program as the following: 


NAME (QGPL/A USER/B) 


Defining a Dependent Relationship 

If a required relationship exists between parameters, and if parameter values must 

be checked when the command is run, use the Dependent (DEP) statement to 

define that relationship. Using the DEP statement, you can perform the functions 

that are listed below: 

* Specify the controlling conditions that must be true before the parameter 
relationships defined in the PARM parameter need to be true (CTL). 

* Specify the parameter relationships that require testing if the controlling 
conditions defined by CTL are true (PARM). 

* Specify the number of parameter relationships that are defined on the associated 
PARM statement that must be true if the control condition is true (NBRTRUE). 

* Specify the message identifier of an error message in a message file that the 
system is to send to the display station user if the parameter dependencies have 
not been satisfied. 


In the following example, if the display station user specifies the TYPE(LIST) 
parameter, the display station user must also specify the ELEMLIST parameter. 


DEP CTL(&TYPE *EQ LIST) PARM(ELEMLIST) 


In the following example, the parameter &WRITER must never be equal to the 
parameter &NEWWTR. If this condition is not true, message USRO001 is issued to 
the display station user. 


DEP CTL(*ALWAYS) PARM((&WRITER *NE &NEWWTR)) MSGID(USROQ01) 


In the following example, if the display station user specifies the FILE parameter, 
the display station user must also specify both the VOL and LABEL parameters. 


DEP CTL(FILE) PARM(VOL LABEL) NBRTRUE(*EQ 2) 


Possible Choices and Values 


The prompter will display possible choices for parameters to the right of the input 
field on the prompt displays. The text to be displayed can be created automatically, 
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specified in the command definition source, or created dynamically by an exit 
program. Text describing possible choices can be defined for any PARM, ELEM, or 
QUAL statement, but because of limitations in the display format, the text is 
displayed only for values with a field length of 12 or less, 10 or less for all but the 
first qualifier in a group. 


The text for possible choices is defined by the CHOICE parameter. The default for 
this parameter is *VALUES, which indicates that the text is to be created 
automatically from the values specified for the TYPE, RANGE, VALUES, SPCVAL, 
and SNGVAL keywords. The text is limited to 30 characters; if there are more 
values than can fit in this size, an ellipsis (...) is added to the end of the text to 
indicate that it is incomplete. 


You can specify that no possible choices should be displayed (*NONE), or you can 
specify either a text string to be displayed or the ID of a text message which is 
retrieved from the message file specified in the PMTFILE parameter of the 
CRTCMD command. 


You can also specify that an exit program to run during prompting to provide the 
possible choices text. This could be done if, for example, you want to show the 
user a list of objects that currently exist on the system. The same exit program can 
be used to provide the list of permissible values shown on the Specify Value for 
Parameter display. To specify an exit program, specify *PGM for the CHOICE 
parameter, and the qualified name of the exit program in the CHOICEPGM 
parameter on the PARM, ELEM, or QUAL statement. 


The exit program must accept the following two parameters: 


* Parameter 1: A 21-byte field that is passed by the prompter to the choice 
program, and contains the following: 


Positions 
Descriptions 


1-10 | Command name. Specifies the name of the command being processed 
that causes the program to run. 


11-20 Keyword name. Specifies the keyword for which possible choices or 
permissible values are being requested. 


21 C or P character indicating the type of data being requested by 
prompter. The letter C indicates that this is a 30-byte field into which the 
text for possible choices is to be returned. The letter P indicates that this 
a 2000-byte field into which a permissible values list is to be returned. 


* Parameter 2: A 30- or 2000-byte field for returning one of the following: 


— If C is in byte 21 of the first parameter, this indicates that the text for possible 
choices will return. Additionally, this is a 30-byte field where the program 
places the text to the right of the input field on the prompt display. 

— If P is in byte 21 of the first parameter (indicating that a permissible values 
list is to be returned), this is a 2000-byte field into which the program is to 
place the list. The first two bytes of the list must contain the number of 
entries (in binary) in the list. This value is followed by entries that consist of a 
2-byte binary length followed by the value, which must be 1 to 32 characters 
long. 

If a binary zero value is returned in the first two bytes, no permissible values 
are displayed. 
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If a binary negative value is returned in the first two bytes, the list of 
permissible values is taken from the command. 


If any exception occurs when the program is called, the possible choices text is left 
blank, and the list of permissible values is taken from the command. 


Using Prompt Control 


You can control which parameters are displayed for a command during prompting 
by using prompt control specifications. This control can simplify prompting for a 
command by displaying only the parameters that you want to see. 


You can specify that a parameter be displayed depending on the value specified 
for other parameters. This specification is useful when a parameter has meaning 
only when another parameter (called a controlling parameter) has a certain value. 


You can also specify that a parameter be selected for prompting only if additional 
parameters are requested by pressing a function key during prompting. This 
specification can be used for parameters that are seldom specified by the user, 
either because the default is normally used or because they control seldom-used 
functions. 


If you want to show all parameters for a command that has prompt control 
specified, you can request that all parameters be displayed by pressing F9 during 
prompting. 


Conditional Prompting 


When prompting the user for a command, a parameter which is conditioned by 
other parameters is displayed if: 


* It is selected by the value specified for the controlling parameter. 
* The value specified for the controlling parameter is in error. 
* A value was specified for the conditioned parameter. 


* A function key was pressed during prompting to request that all parameters be 
displayed. 


When a user is to be prompted for a conditioned parameter and no value has yet 
been specified for its controlling parameter, all parameters previously selected are 
displayed. When the user presses the Enter key, the controlling parameter is then 
tested to determine if the conditioned parameter should be displayed or not. 


To specify conditional prompting in the command definition source, specify a label 
name in the PMTCTL parameter on the PARM statement for each parameter that is 
conditioned by another parameter. The label specified must be defined on a 
PMTCTL statement which specifies the controlling parameter and the condition 
being tested to select the parameter for prompting. More than one PARM 
statement can refer to the same label. 


On the PMTCTL statement, specify the name of the controlling parameter, one or 
more conditions to be tested, and the number of conditions that must be true to 
select the conditioned parameters for prompting. If the controlling parameter has 
special value mapping, the value entered on the PMTCTL statement must be the 
to-value. If the controlling parameter is a list or qualified name, only the first list 
item or qualifier is compared. 
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In the following example, parameters OUTFILE and OUTMBR is selected only if 
*“OUTFILE is specified for the OUTPUT parameter, and parameter OUTQ is 
selected only if *PRINT is specified for the OUTPUT parameter. 

PARM OUTPUT TYPE(*CHAR) LEN(1) DFT(*) RSTD(*YES) + 

SPCVAL((*) (*PRINT P) (*OUTFILE F)) 

PARM OUTFILE TYPE(Q1) PMTCTL(OUTFILE) 

PARM OUTMBR TYPE(*NAME) LEN(10) PMTCTL(OUTFILE) 

PARM OUTLINK TYPE(*CHAR) LEN(10) 

PARM OUTQ TYPE(Q1) PMTCTL(PRINT) 

Ql: QUAL TYPE(*NAME) LEN(10) 

QUAL TYPE(*NAME) LEN(10) SPCVAL(*LIBL) DFT(*LIBL) 

QUTFILE: PMTCTL CTL(OUTPUT) COND((*EQ F)) NBRTRUE(*EQ 1) 
PRINT: PMTCTL CTL(OUTPUT) COND((*EQ P)) NBRTRUE(*EQ 1) 


In this previous example, the user is prompted for the OUTLINK parameter after 
the condition for OUTMBR parameter has been tested. In some cases, the user 
should be prompted for the OUTLINK parameter before the OUTMBR parameter 
is tested. To specify a different prompt order, either reorder the parameters in the 
command definition source or use the PROMPT keyword on the PARM statement 
for the OUTLINK parameter. 


A label can refer to a group of PMTCTL statements. This allows you to condition a 
parameter with more than one controlling parameter. To specify a group of 
PMTCTL statements, enter the label on the first statement in the group. No other 
statements can be placed between the PMTCTL statements in the group. 


Use the LGLREL parameter to specify the logical relationship between the 
statements in the group. The LGLREL parameter is not allowed on the first 
PMTCTL statement in a group. For subsequent PMTCTL statements, the LGLREL 
parameter specifies the logical relationship (*AND or *OR) to the PMTCTL 
statement or statements preceding it. Statements in a group can be logically related 
in any combination of *AND and *OR relationships (*AND relationships are 
checked first, then *OR relationships). 


The following example shows how the logical relationship is used to group 
multiple PMTCTL statements. In this example, parameter P3 is selected when any 
one of the following conditions exists: 


* *ALL is specified for P1. 
* *SOME is specified for P1 and *ALL is specified for P2. 
* *NONE is specified for P1 and *ALL is not specified for P2. 


PARM P1 TYPE(*CHAR) LEN(5) RSTD(*YES) VALUES(*ALL *SOME *NONE) 
PARM P2 TYPE(*NAME) LEN(10) SPCVAL(*ALL) 
PARM P3 TYPE(*CHAR) LEN(10) PMTCTL(PMTCTL1) 
PMTCTL1:PMTCTL CTL(P1) COND((*EQ *ALL)) 
PMTCTL CTL(P1) COND((*EQ *SOME)) LGLREL(*OR) 
PMTCTL CTL(P2) COND((*EQ *ALL)) LGLREL(*AND) 
PMTCTL CTL(P1) COND((*EQ *NONE)) LGLREL(*OR) 
PMTCTL CTL(P2) COND((*NE *ALL)) LGLREL(*AND) 


An exit program can be specified to perform additional processing on a controlling 
parameter before it is tested. The exit program can be used to condition prompting 
based on: 


* The type or other attribute of an object 
* A list item or qualifier other than the first one 
* An entire list or qualified name 
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To specify an exit program, specify the qualified name of the program in the 
PMTCTLPGM parameter on the PARM statement for the controlling parameter. 
The exit program is run during prompting when checking a parameter. The 


conditions on the PMTCTL statement are compared with the value returned by the 


exit program rather than the value specified for the controlling parameter. 


When the system cannot find or successfully run the exit program, the system 
assumes any conditions that would use the returned value as true. 


The exit program must be written to accept three parameters: 


* A 20-character field. The prompter passes the name of the command in the first 
10 characters and the name of the controlling parameter in the last 10 characters. 


This field should not be changed. 


* The value of the controlling parameter. This field is in the same format as it is 
when passed to the command processing program and should not be changed. 


* If the controlling parameter is defined as VARY(*YES) the value is not preceded 
by a length value. If the controlling parameter is PASSATR(*YES), the attribute 


byte is not included. 


* A 32-character field into which the exit program places the value to be tested in 


the PMTCTL statements. 


The value being tested in the PMTCTL statement must be returned in the same 


format as the declared data type. 


In the following example, OBJ is a qualified name which may be the name of a 
command, program, or file. The exit program determines the object type and 


returns the type in the variable &RTNVAL: 


CMD 
PARM OBJ TYPE(Q1) PMTCTLPGM(CNVTYPE) 
Q1: QUAL TYPE(*NAME) LEN(10) 
QUAL TYPE(*NAME) LEN(10) SPCVAL(*LIBL) DFT(*LIBL) 
PARM CMDPARM TYPE(*CHAR) LEN(10) PMTCTL(CMD) 
PARM PGMPARM TYPE(*CHAR) LEN(10) PMTCTL(PGM) 
PARM FILEPARM TYPE(*CHAR) LEN(10) PMTCTL(FILE) 
CMD: PMTCTL CTL(OBJ) COND((*EQ *CMD) (*EQ *)) NBRTRUE(*EQ 1) 
PGM: PMTCTL CTL(OBJ) COND((*EQ *PGM) (*EQ *)) NBRTRUE(*EQ 1) 
FILE: PMTCTL CTL(OBJ) COND((*EQ *FILE) (*EQ *)) NBRTRUE(*EQ 1) 


The source for the exit program is shown here: 
PGM PARM(&CMD &PARMVAL &RTNVAL) 


DCL &CMD *CHAR 20 /* Command and parameter name */ 
DCL &PARMVAL *CHAR 20 /* Parameter value */ 
DCL &RTNVAL *CHAR 32 /* Return value */ 
DCL &OBJNAM *CHAR 10 /* Object name x/ 
DCL &OBJLIB *CHAR 10 /* Object type */ 
CHGVAR &OBJNAM %SST(&PARMVAL 1 10) 

CHGVAR &OBJLIB %SST(&PARMVAL 11 10) 

CHGVAR &RTNVAL '*' /* Initialize return value to error*/ 
CHKOBJ &OBJLIB/&0BJNAM *CMD /* See if command exists */ 
MONMSG CPF9801 EXEC(GOTO NOTCMD) /* Skip if no command */ 
CHGVAR &RTNVAL '*CMD' /* Indicate object is a command */ 
RETURN /* Exit x/ 
NOTCMD: 

CHKOBJ &OBJLIB/&0BJNAM *PGM /* See if program exists */ 
MONMSG CPF9801 EXEC(GOTO NOTPGM) /* Skip if no program */ 
CHGVAR &RTNVAL '*PGM' /* Indicate object is a program */ 
RETURN /* Exit x/ 
NOTPGM: 
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CHKOBJ &0BJLIB/&0BJNAM *FILE /* See if file exists */ 


MONMSG CPF9801 EXEC(RETURN) /* Exit if no file */ 
CHGVAR &RTNVAL '*FILE' /* Indicate object is a file */ 
ENDPGM 


Additional Parameters 


You can specify that a parameter which is not frequently used will not be 
prompted for unless the user requests additional parameters by pressing a function 
key during prompting. This is done by specifying PMTCTL(*PMTRQS) on the 
PARM statement for the parameter. When prompting for a command, parameters 
with PMTCTL(#*PMTRQS) coded will not be prompted unless a value was specified 
for them or the user presses F10 to request the additional parameters. 


The prompter displays a separator line before the parameters with 
PMTCTL(?*PMTRQS) to distinguish them from the other parameters. By default, all 
parameters with PMTCTL(*PMTRQS) are prompted last, even though they are not 
defined in that order in the command definition source. You can override this by 
specifying a relative prompt number in the PROMPT keyword. If you do this, 
however, it can be difficult to see what parameters were added to the prompt 
when F10 is pressed. 


Using Key Parameters and a Prompt Override Program 


The prompt override program allows current values rather than defaults to be 
displayed when a command is prompted. 


If a prompt override program is defined for a command, you can see the results of 
calling the prompt override program in the following two ways: 


* Type the name of the command without parameters on any command line and 
press F4=Prompt. The next screen shows the key parameters for the command. 
Key parameters are parameters, such as the name of an object, that uniquely 
identify the object. 


Complete all fields shown and press the Enter key. The next screen shows all 
command parameters, and the parameter fields that are not key parameter fields 
contain current values rather than defaults (such as *SAME and *PRV). 


For example, if you type CHGLIB on a command line and press F4=Prompt, you 
see only the Library parameter. If you then type *CURLIB and press the Enter 
key, the current values for your current library are displayed. 


* Type the name of the command and the values for all key parameters on any 
command line. Press F4=Prompt. The next screen shows all command 
parameters, and the parameter fields that are not key parameter fields will 
contain current values rather than defaults (such as *SAME and *PRV). 


For example, if you type CHGLIB LIB(*CURLIB) on a command line and press 
F4=Prompt, the current values for your current library are displayed. 


When F10=Additional parameters is pressed, any parameters defined with 
PMTCTL(?*PMTRQS) are displayed_with current values. For more information 
about additional parameters, see 


To exit the command prompt, press F3=Exit. 


Procedure for Using Prompt Override Programs 


To use a prompt override program, do the following: 
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1. Specify any parameters that are to be key parameters on the PARM statement 
in the command definition source. For information ebaut the KEYPARM 
parameter, see the following section, 


2. Write a prompt override program. For information about creating prompt 


override programs, see 


3. Specify the name of the eu override program on the PMTOVRPGM 
parameter when you create or change the command. For information about 
creating or changing commands that use the prompt override program, see 


Identifying Key Parameters 
The number of key parameters should be limited to the number of parameters 
needed to uniquely define the object to be changed. 


To ensure a key parameter is coded correctly in the command definition source, do 

the following: 

* Specify KEYPARM(*YES) on the PARM statement in the command definition 
source. 

* Define all parameters that specify KEYPARM(*YES) before all parameters that 
specify KEYPARM(*NO). 


Note: If a PARM statement specifies KEYPARM(*YES) after a PARM statement 
that specifies KEYPARM(*NO), the parameter is not treated as a key 
parameter and a warning message is issued. 

* Do not specify a MAX value greater than one in the PARM statement. 

* Do not specify a MAX value greater than one for ELEM statements associated 
with key parameters. 

* Do not specify *PMTRQOS or a prompt control statement for the PMTCTL 
keyword on the PARM statement. 

* Place key parameters in the command definition source in the same order you 
want them to appear when prompted. 


Writing a Prompt Override Program 

A prompt override program needs to be passed certain information to return 
current values when a command is prompted. You must consider both the passed 
information and the returned values when you write a prompt override program. 


For an example of CL source for a prompt override program, see VCL Sample for 


Parameters Passed to the Prompt Override Program: The prompt override 

program is passed the following parameters: 

¢ A 20-character field. The first 10 characters of the field contain the name of the 
command and the last 10 characters contain the name of the library. 


* A value for each key parameter, if any. If more than one key parameter is 
defined, the parameter values are passed in the order that the key parameters 
are defined in the command definition source. 

* A 32676-byte (32K) space to hold the command string that is created by the 
prompt override program. The first two bytes of this field must contain the 
hexadecimal length of the command string that is returned. The actual command 
string follows the first two bytes. 


For example, when defining two key parameters for a command, four 
parameters pass to the prompt override program as follows: 
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— One parameter for the command. 
— Two parameters for the key parameters. 


— One parameter for the command string space. 


Information Returned from the Prompt Override Program: Based on the values 
passed, the prompt override program retrieves the current values for the 
parameters that are not key parameters. These values are placed into a command 
string, where the length of the string is determined and returned. 


Use the following guidelines to ensure your command string is correctly defined: 


* Use the keyword format for the command string just as you would on the 
command line. 

* Do not include the command name and the key parameters in the command 
string. 


* Precede each keyword with a selective prompt character to define how to 
display the parameter and what value to pass to the CPP. For information about 


a selective prompt characters, see (‘Sele ompting fo ommand 


When using selective prompts, do the following: 


— Ifa parameter is defined as MIN(1) in the command definition source (that is, 
the parameter is required), you must use the ?? selective prompt character for 
that keyword in the command string from the prompt override program. 


— Do not use the ?- selective prompt character in the prompt override program 
command string. 


The following example shows a command string returned from a prompt 

override program: 

??Number (123456) ?<Qualifier(CLIB/CFILE) ?<LIST(ITEM1 ITEM2 ITEM3) ?<TEXT('Carol's file’) 
* Make sure that the specified value in the first two bytes of the space the 

program passes is the actual hexadecimal length of the command string. 


5700-byte space 


0024 | ??NAME(CAROL) ?4FILE(CHWLIB/CJWFILE)... 


Length of command string (in hexidecimal) 


Command String 


RBAFN501-0 


* Include only the parameters in the command string whose current values you 
want displayed when the command is prompted. Parameters not included in the 
command string have their defaults displayed. 


* Use character form for any numbers that appear in the command string. Do not 
use binary or packed form. Do not include any hexadecimal numbers in the 
command string. 

* Do not put blank spaces between the library and the qualifier or the qualifier 
and the object. For example: 


??KWD1(library /object) 
Not valid 


??KWD1(library/ object) 
Not valid 
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??KWD1(library/object) 
Valid 


??KWD1( ‘library/object ) 
Valid 
* If you use special values or single values, make sure they are translated into the 
from-value defined in the command definition source. 


For example, a keyword has a special value defined as SPCVAL(*SPECIAL *) in 
the command definition source. *SPECIAL is the from-value and * is the 
to-value. When the current value is retrieved for this keyword, * is the value 
retrieved, but *SPECIAL must appear in the command string returned from the 
prompt override program. The correct from-value must be placed into the 
command string since more than one special value or single value can have the 
same to-value. For example, if KWD1 SPCVAL((*SPC *) (*SPECIAL *)) is specified, 
the prompt override program must determine whether * is the to-value for *SPC 
or *SPECIAL. 


* Define the length of fields used to retrieve text as follows: 
(2*(field length defined in command definition source)) + 2 


This length allows for the maximum number of quotation marks allowed in the 
text field. For example, if the TEXT parameter on the CHGxxx command is 
defined in the command definition source as LEN(50), then the parameter is 


declared as CHAR(102) in its prompt override program. For an example of how 
to define the length of fields used to retrieve text, see ECL Sample for Using thd 


If the parameter for a text field is not correctly defined in the prompt override 
program and the text string retrieved by the prompt override program contains 
a quote, the command does not prompt correctly. 


* Make sure that you double any embedded apostrophes, for example: 
2?<TEXT('Carol''s library') 


Some commands can only be run in certain modes (such as DEBUG) or job status 
(such as *BATCH) but can still be prompted for from other modes or job statuses. 
When the command is prompted, the prompt override program is called regardless 
of the user’s environment. If the prompt override program is called in a mode or 
environment that is not valid for the command, the defaults are displayed for the 
command and a value of 0 is returned for the length. Using the debug commands 
Change Debug (CHGDBG) and Add Program (ADDPGM) when not in debug 
mode are examples of this condition. 


Allowing for Errors in a Prompt Override Program: If the prompt override 

program detects an error, it should do the following: 

* Set the command string length to zero so that the defaults rather than current 
values are displayed when the command is prompted. 


* Send a diagnostic message to the previous call. 
* Send escape message CPFO0011. 


For example, if you need a message saying that a library does not exist, add a 
message description similar to the following: 


ADDMSGD MSG('Library &2 does not exist') + 
MSGID(USRO012) + 
MSGF(QGPL/ACTMSG) + 
SEV(40) + 
FMT((*CHAR 4) (*CHAR 10)) 
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Note: The substitution variable &1 is not in the message but is defined in the FMT 
parameter as 4 characters. &1 is reserved for use by the system and must 
always be 4 characters. If the substitution variable &1 is the only 
substitution variable defined in the message, you must ensure that the 
fourth byte of the message data does not contain a blank when you send the 
message. The fourth byte is used by the system to manage messages during 
command processing and prompting. 


This message can be sent to the calling program of the prompt override program 
by specifying the following in the prompt override program: 
SNDPGMMSG  MSGID(USROO12) MSGF(QGPL/ACTMSG) + 

MSGDTA('0000' || &libname) MSGTYPE(*DIAG) 


After the prompt override program sends all the necessary diagnostic messages, it 
should then send message CPF0011. To send message CPFO0011, use the Send 
Program Message (GNDPGMMSG) command as follows: 


SNDPGMMSG § MSGID(CPFO011) MSGF(QCPFMSG) + 
MSGTYPE (*ESCAPE) 


When message CPFO0011 is received, message CPD680A is sent to the calling 
program and displayed on the prompt screen to indicate that errors have been 
found. All diagnostic messages are placed in the user’s job log. 


Specifying the Prompt Override Program When Creating or 
Changing Commands 

To use a prompt override program for a command you want to create, specify the 
program name when you use the Create Command (CRTCMD) command. You can 
also specify the program name when you change the command using the Change 
Command (CHGCMD) command. For both commands, specify the name of the 
prompt override program on the PMTOVRPGM parameter. 


If key parameters are defined in the command definition source but the prompt 
override program is not specified when the command is created or changed, 
warning message CPD029B results. The key parameters are ignored, and when the 
command is prompted, it is displayed using the defaults specified in the command 
definition source. 


Sometimes a prompt override program is specified when a command is created but 
when no key parameters are defined in the command definition source. In these 
cases, the prompt override program is called before the command is prompted; 
informational message CPD029A is sent when the command is created or changed. 


CL Sample for Using the Prompt Override Program 


The following example shows the command source for a command and the 
prompt override program. This command allows the ownership and text 
description of a library to be changed. The prompt override program for this 
command receives the name of the library; retrieves the current value of the library 
owner and the text description; and then places these values into a command 
string and returns it. 


This prompt override program uses the "?4" selective prompt characters. 
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Sample Command Source 


CHGLIBATR: CMD PROMPT('Change Library Attributes') 
PARM KWD(LIB) + 
TYPE(*CHAR) MIN(1) MAX(1) LEN(10) + 
KEYPARM(*YES) + 
PROMPT('Library to be changed') 
PARM KWD(OWNER) + 
TYPE(*CHAR) LEN(10) MIN(O) MAX(1) + 
KEYPARM(*NO) + 
PROMPT('Library owner') 
PARM KWD(TEXT) + 
TYPE(*CHAR) MIN(Q) MAX(1) LEN(50) + 
KEYPARM(*NO) + 
PROMPT('Text description’) 


Sample Prompt Override Program 


PGM PARM(&cmdname &keyparml &rtnstring) 


[RRR K KER KKK AK ERIK RAK KEKE KEIR KEKE IKKE AK KEK KIRA KEK KEKE AKA | 


/* */ 
/* Declarations of parameters passed to the prompt override program */ 
/* */ 


[KERR KKK KK KKK KKK KKK KKK KEIR KKK KKK AK KAKA KKK KKK KKK AK EKA KERR | 
DCL VAR(&cmdname) TYPE(*CHAR) LEN(20) 

DCL VAR(&keyparml) | TYPE(*CHAR) LEN(10) 

DCL VAR(&rtnstring) TYPE(*CHAR) LEN(5700) 


[RRR KKK AKER A KKK KKK KKK KKK AK KEIR AK KKK KKK KKK KKK AK KEK AKER AKER KK | 


/* x/ 
/* Return command string structure declaration x/ 
/* x/ 


[RRR KER KKK KKK A KKK KKK KKK EA KKK AK KK IKK KKK KKK AK KIRKE IKKE KK KEAA KEKE | 


/* Length of command string generated x/ 
DCL VAR(&stringlen) TYPE(*DEC) LEN(5 0) VALUE(131) 
DCL VAR(&binlen) TYPE(*CHAR) LEN(2) 


/* OWNER keyword */ 
DCL VAR(&ownerkwd) TYPE(*CHAR) LEN(8) VALUE('?<OWNER(') 
DCL VAR(&name) TYPE(*CHAR) LEN(10) 

/* TEXT keyword */ 


DCL VAR(&textkwd)  TYPE(*CHAR) LEN(8) VALUE(' ?<TEXT(‘) 
DCL VAR(&descript) TYPE(*CHAR) LEN(102) 


[KERR KER AKER KKK A KKK KKK AKA KKK KKK KK KKK KKK KK IKKE AK KEK KEE A KEKE KE | 


/* x/ 
/* Variables related to command string declarations x/ 
/* x/ 
[KERR KER AKER A KKK KKK KKK IKKE AK KEK KKK KKK IK KKK KK KIRKE AK KEK KKK KARE KE | 
DCL VAR(&quote) TYPE(*CHAR) LEN(1) VALUE('''') 


DCL VAR(&closparen) TYPE(*CHAR) LEN(1) VALUE(')') 
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[RRR KKK AKER AKER A KKK IKEA KKK IKKE KK KKK KKK AKER AKAIKE RAKE KARE KK | 


/* 
/* 
/* 


Start of operable code 


*/ 
*/ 
*/ 


[KERR KKK AKER A KKK KKK IKEA KKK IK KEK KKK KKK AKI KKK KAKA KKK AKER AREER KE | 


[RRR RK RRA KKK AK KKK KK IKEA KKK I KKK KKK KKK KKK KK KKK A AKA KKK AREA AKER KK | 


/* 
/* Monitor 
/* 


for exceptions 


*/ 
*/ 
*/ 


[RRR KKK KKK A KKK KKK IKK A KKK IK KEK KKK KKK KKK KKK A KKK KKK AREA KEE KK | 


MONMSG MSGID(CPFOQ00) + 
EXEC(GOTO CMDLBL(error) ) 


[BRK R KER A KERIKERI KKK AKER K KK EAR KKK KERIKERI KKK AK KAKA KKK AKER AKER | 


/* x/ 
/* Retrieve the owner and text description for the library specified*/ 
/* on the LIB parameter. Note: This program assumes there are x/ 
/* no apostrophes in the TEXT description, such as (Carol's) */ 

/* x/ 


[KERR KKK A KKK KKK K KA KKK KKK IK KKK KKK KKK IKK KKK KAKA KKK AEE K KER KK | 


RTVOBJD OBJ(&keyparm1) OBJTYPE(*LIB) OWNER(&name) TEXT(&descript) 


CHGVAR VAR(%BIN(&binlen)) VALUE(&stringlen) 


[KERR KER KKK AKERA KEK AKKK KK EAR KKK KERIKERI KKK IKK IKKE AK KEK AEE KARE KK | 


/* 


/* Build the command string 


/* 


*/ 
*/ 
*/ 


[BRK R KEK AKER AKER IKK AK KK KK EAR KERIKERI KKK IKEA KK EAA AEE AKEREK KE | 


CHGVAR 
CHGVAR 
CHGVAR 
CHGVAR 
CHGVAR 
CHGVAR 
CHGVAR 
CHGVAR 
CHGVAR 


VAR(&rtnstring) 
VAR(&rtnstring) 
VAR(&rtnstring) 
VAR(&rtnstring) 
VAR(&rtnstring) 
VAR(&rtnstring) 
VAR(&rtnstring) 
VAR(&rtnstring) 
VAR(&rtnstring) 


GOTO CMDLBL(pgmend) 


ERROR: 


VALUE (0) 
CHGVAR VAR(%BIN(&rtnstring 1 2)) VALUE(&stringlen) 
VALUE (&binlen) 
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VALUE (&binlen) 

VALUE (&rtnstring 
VALUE (&rtnstring 
VALUE (&rtnstring 
VALUE (&rtnstring 
VALUE (&rtnstring 
VALUE (&rtnstring 
VALUE (&rtnstring 
VALUE (&rtnstring 


*TCAT 
*TCAT 
*TCAT 
*TCAT 
*TCAT 
*TCAT 
*TCAT 
*TCAT 


&ownerkwd) 
&name) 
&closparen) 
&textkwd) 
&quote) 
&descript) 
&quote) 
&closparen) 


[KERR KER AKER A KKK KKK KKK ARK IK KKK KKK KKK KKK KAKI K IKEA KKK KEKE KK | 


/* x/ 
/* Send error message(s) */ 
/* x/ 
/* NOTE: If you wish to send a diagnostic message as well as CPFOOQ11*/ 
/* you will have to enter a valid error message ID in the */ 
/* MSGID parameter and a valid message file in the MSGF x/ 
/* parameter for the first SNGPGMMSG command listed below. x/ 
/* If you do not wish to send a diagnostic message, do not x/ 
/* include the first SNDPGMMSG your program. However, in */ 
/* error conditions, you must ALWAYS send CPFO011 so the */ 
/* second SNDPGMMSG command must be included in your program. */ 
/* x/ 


[RRR KK ERA KKR KKK KKK KKK KKK AK KKK KK AK KKK KKK KKK KEI KKK KKK AK KEKE KE | 


SNDPGMMSG MSGID(XXXXXXX) MSGF(MSGLIB/MSGFILE) MSGTYPE(*DIAG) 
SNDPGMMSG MSGID(CPF0011) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) 


PGMEND: 
ENDPGM 


Creating Commands 


After you have defined your command through the command definition 
statements, you use the Create Command (CRTCMD) command to create the 
command. Besides specifying the command name, library name, and command 
processing program name for CL or high-level languages (HLL), or the source 
member, source file, command environment, and exit program for REXX, you can 
define the following attributes of the command: 


The validity checking used by the command 
The modes in which the command can be run 
— Production 

— Debug 

— Service 

Where the command can be used 

— Batch job 

— Interactive job 

— ILE CL module in a batch job 

— CL program in a batch job 

- ILE CL module in an interactive job 

— CL program in an interactive job 

— REXX procedure in a batch job 

— REXX procedure in an interactive job 


- As acommand interpretively processed by the system through a call to 
QCMDEXC (see Ehanterd for information about QCMDEXC) 


The maximum number of parameters that can be specified by position 

The message file containing the prompt text 

The help panel group that is used as help for promptable parameters 

The help identifier name for the general help module used on this command 
The message file containing the messages identified on the DEP statement 
The current library to be active during command processing 

The product library to be active during command processing 
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* Whether an existing command with the same name, type, and library is replaced 
if REPLACE(*YES) is specified. 


* The authority given to the public for the command and its description 
* Text that briefly describes the command and its function 


For commands with REXX CPPs, you can also specify the following: 


* The initial command environment to handle commands when the procedure is 
started 


* Exit programs to control running of your procedure 


The following example defines a command named ORDENTRY to call an order 
entry application. The CRTCMD command defines the preceding attributes for 
ORDENTRY and creates the command using the parameter definitions contained 
in the member ORDENTRY in the IBM-supplied source file QCMDSRC. 
ORDENTRY contains the PARM statement used in the example under 


CRTCMD CMD(DSTPRODLB/ORDENTRY) + 
PGM(*LIBL/ORDENT) + 
TEXT('Calls order entry application') 


The resulting command is: 
ORDENTRY OETYPE(value) 


where the value can be DAILY, WEEKLY, or MONTHLY. 


Once you have created a command, you can: 


* Display the attributes of the command by using the Display Command 
(DSPCMD) command 


* Change the attributes of the command by using the Change Command 
(CHGCMD) command 


* Delete the command by using the Delete Command (DLTCMD) command 


Command Definition Source Listing 


When you create a command, a source list is produced. The following shows a 
sample source list. The numbers refer to descriptions following the list. 


5769SS1 V4R5MO 990521 fy Command Definition DSTPRODLB/ORDENTRY 11/20/98 14:53:32 EJ Page m3] 
Command: MAME: eve eck us wae. ce wie es ae ee a :  ORDENTRY 
ET DRARY 66. G8 ese cas te BS ae ee pe ew : DSTPRODLB 
Command processing program ......... :  ORDENT 4] 
METER AY! a eroasae cre ogy say os Wage ees cay ee ie ae : *LIBL 
SOUPCE: TIME se ee oe. x iss vine Set eevee pena ae fae a ee :  QCMDSRC 
LT BRARY os ete Ao aoe. Sok a ee ON 2S QGPL 
Source file member ..........04. :  ORDENTRY 11/20/98 14:54:32 
Validity checker program ..........: *NONE 
Mode in which valid... 1... 2 ee wane :  *PROD 
*DEBUG 
*SERVICE 
Environment allowed... .... 2... 4. 2  *IREXX 
*BREXX 
*BPGM 
*IPGM 
*EXEC 
* INTERACT 
*BATCH 
*BMOD 
*IMOD 
Allow limited user 2... 2... 2.2.6.4. :  *NO 
Max positional parameters. ......... :  *NOMAX 
POMPE PENG: a. iar i cei ade a ea we nae ae GP :  *NONE 
Message file ..........2.4.4+.4. 2: QCPFMSG 
[ST BYATEY. e- 58 ca oe. 4s tana ce ene cake He eae 5 *LIBL 
AUCMOVEEY: se cat ve, oi wee a a ed ee Sr SS :  *LIBCRTAUT 
Replace command... 1... 2. eee eee 2 *YES 
Enable graphical user interface. ...... > *NO 
Threadsafe 66. be ee ee ee eee os *NO 
Multithreaded job action .......... :  *SYSVAL 
TEGXE:  cepeidss day Gdn ver WR: SRY ah Har Sor heater va Jae Sa a, Poe : Calls order entry application 
Help book name: a o.ce tarde ee ce es eee oe we :  *NONE 
Help: bookshelf... 6-4 ete ek ee ee ee > *NONE 
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Help panel group ........22.20008 :  *NONE 


Help: Tdentitier 6.6 4 bee se ee a eae > *NONE 
Help search index... ........... 2  *NONE 
CUPYENE. WIDLARY sec ie: lee, eee oe ee a ae :  *NOCHG 
Product. library’ ed es aoe ares tae ee ne was :  *NOCHG 
Prompt override program... ......0. :  *NONE 
COMPT TSR: as: cag ce eo Bie ae Sw SO eS te ee : IBM AS/400 Command Definition Compiler 


Command Definition Source 


G 
SEQNBR: “#3207 pe Db aadBeaa 2 ccoePeaa Saath: A ee tage ior dhl Bee BO siesta HE. Geta Bi aetiang DS cat DATE o 
- 100- CMD PROMPT('Order entry command') 11/20/98 
a 

200- PARM KWD(OETYPE) TYPE(*CHAR) RSTD(*YES) + 11/20/98 

300 VALUES (DAILY WEEKLY MONTHLY) MIN(1) + 11/20/98 

400 PROMPT('Type of order entry:') 11/20/98 

**ee** END OF S OURCE ** *** 

5769SS1 V4R4M0 990521 Command Definition DSTPRODLB/ORDENTRY 11/20/98 14:54:32 Page 2 


Cross Reference 


Defined Keywords [J 


Keyword Number Defined References 
OETYPE 001 200 
xe *x*e* END OF CROSS REFERENCE ** * * * 
5769SS1 V4R4M0 990521 Command Definition DSTPRODLB/ORDENTRY 11/20/98 14:54:32 Page 3} 
Final Messages 
Message Sequence 
ID Number Sev Text 
Message Summary 
Total Info Error 
0 0 () 
* CPCO202 00 Command ORDENTRY created in library DSTPRODLB. 
eee ee END OF COMPILATION ** * * * 
Title: 


2 


The program number, version, release, modification level, and date of 
OS/400. 


The date and time of this run. 


The page number in the list. 


Prologue 


Source: 


[co Hl ~ 


The parameter values specified (or defaults if not specified) on the 
CRTCMD command. If the source is not in a database file, the member 
name, date, and time are omitted. 


The name of the create command definition compiler. 


The sequence number of lines (records) in the source file. A dash following 
a sequence number indicates that a source statement begins at that 
sequence number. The absence of a dash indicates that a statement is the 
continuation of the previous statement. For example, a PARM source 
statement starts at sequence number 200 and continues at sequence 
numbers 300 and 400. (Note the continuation character of + on the PARM 
statement at sequence number 200 and 300.) 


Comment source statements are handled like any other source statement 
and have sequence numbers. 


The source statements. 


The last date the source statement was changed or added. If the statement 
has not been changed or added, no date is shown. If the source is not in a 
database file, the date is omitted. 


If an error is found during processing of the command definition 
statements and can be traced to a specific source statement, the error 
message is printed immediately following the source statement. An asterisk 
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(*) indicates that the line contains an error message. The line contains the 
message identifier, severity, and the text of the message. 


For more information about the command definition errors, see (‘Error 


Cross-references: 


9 | The keyword table is a cross-reference list of the keywords validly defined 
in the command definition. The table lists the keyword, the position of the 
keyword in the command, the sequence number of the statement where 
the keyword is defined, and the sequence numbers of statements that refer 
to the keyword. 


If valid labels are defined in the command definition, a cross-reference list 
of the labels (label table) is provided. The table lists the label, the sequence 
number of the statement where the label is defined, and the sequence 
numbers of statements that refer to the label. 


Messages: 


A list of the general error messages not listed in the source section that 
were encountered during processing of the command definition statements, 
if any. For each message, this section contains the message identifier, the 
sequence number of where the error occurred, the severity, and the 
message. 


Message summary: 


A summary of the number of messages issued during processing of the 
command definition statements. The total number is given along with 
totals by severity. 


A completion message is printed following the message summary. 


Errors Encountered when Processing Command Definition 
Statements 


The types of errors that are caught during processing of the command definition 
statements include syntax errors, references to keywords and labels not defined, 
and missing statements. The following types of errors detected by the command 
definition compiler stop the command from being created (severity codes are 
ignored). 

* Value errors 

° Syntax errors 


Even after an error that stops the command from being created is encountered, the 
command definition compiler continues to check the source for other errors. Syntax 
errors and fixed value errors prevent final checking that identifies errors in user 
names and values or references to keywords or labels. Checking for syntax errors 
and fixed value errors does continue. This lets you see and correct as many errors 
as possible before you try to create the command again. To correct errors made in 
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do not relate to a specific source statement but are more general in nature are 
listed in a messages section of the list, not inline with source statements. 


Displaying a Command Definition 


You can use the Display Command (DSPCMD) command to display or print the 
values that were specified as parameters on the CRTCMD command. The 
DSPCMD command displays the following information for your commands or for 
IBM-supplied commands: 


Qualified command name. The library name is the name of the library in which 
the command being displayed is located. 


Qualified name of the command processing program. The library name is the 
name of the library in which the command processing program resided when 
the command was created if a library name was specified on the CRTCMD or 
CHGCMD command. If a library name was not specified, *LIBL is displayed as 
the library qualifier. If the CPP is a REXX procedure, *REXX is shown. 


Qualified source file name, if the source file was a database file. The library 
name is the name of the library in which the source file was located when the 
CRTCMD command was processed. This field is blank if the source file was not 
a database file. 


Source file member name, if the source file was a database source file. 

If the CPP is a REXX procedure, the following information is shown: 

— REXX procedure member name 

— Qualified REXX source file name where the REXX procedure is located 
— REXX command environment 

— REXX exit programs 


Qualified name of the validity checking program. The library name is the name 
of the library in which the program resided when the command was created if a 
library name was specified on the CRTCMD or CHGCMD command. If a library 
name was not specified, *LIBL is displayed as the library qualifier. 


Valid modes of operation. 
Valid environments in which the command can be run. 


The positional limit for the command. *NOMAxX is displayed if no positional 
limit exists for the command. 


Qualified name of the prompt message file. The library name is the name of the 
library in which the message file was located when the CRTCMD command was 
run. *NONE is displayed if no prompt message file exists for the command. 


Qualified name of the message file for the DEP statement. If a library name was 
specified for the message file when the command was created, that library name 
is displayed. If the library list was used when the command was created, *LIBL 
is displayed. *NONE is displayed if no DEP message file exists for the 
command. 


Qualified name of the help panel group. 
The help identifier name for the command. 
Qualified name for the prompt override program. 


Text associated with the command. Blanks are displayed if no text exists for the 
command. 


Indicator for whether the command prompt is enabled for conversion to a 
graphical user interface. 


Threadsafe indicator. 
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* Multithreaded job action, if the command is not threadsafe. 


Effect of Changing the Command Definition of a Command in a 
Procedure or Program 


When a CL module or program is created, the command definitions of the 
commands in the procedure or program are used to generate the module or 
program. When the CL procedure or program is run, the command definitions are 
also used. If you specify a library name for the command in the CL procedure or 
program, the command must be in the same library at procedure creation time and 
at run time. If you specify *LIBL for the command in the CL procedure or 
program, the command is found, both at procedure creation and run time, using 
the library list (*LIBL). 


You can make the following changes to the command definition statements for a 
command without re-creating the modules and programs that use the command. 
Some of these changes are made to the command definition statements source, 
which requires the command to be re-created. Other changes can be made with the 
Change Command (CHGCMD) command. 


* Add an optional parameter in any position. Adding an optional parameter 
before the positional limit may affect any procedures, programs, and batch input 
streams that have the parameters specified in positional form. 


* Change the REL and RANGE checks to be less restrictive. 


* Add new special values. However, this could change the action of the procedure 
or program if the value could be specified before the change. 


* Change the order of the parameters. However, changing the order of the 
parameters that precede the positional limit will affect any procedures, programs, 
and batch input streams that have the parameters specified in positional form. 


* Increase the number of optional elements in a simple list. 


* Change default values. However, this may affect the operation of the procedure 
or program. 


* Decrease the number of required list items in a simple list. 
* Change a parameter from required to optional. 

* Change RSTD from *YES to *NO. 

* Increase the length when FULL(*NO) is specified. 

* Change FULL from *YES to *NO. 

* Change the PROMPT text. 

* Change the ALLOW value to be less restrictive. 


* Change the name of the command processing program if the new command 
processing program accepts the proper number and type of parameters. 


* Change the name of the validity checking program if the new validity checking 
program accepts the proper number and type of parameters. 


* Change the mode in which the command can be run as long as the new mode 
does not affect the old mode of the same command that is used in a CL 
procedure or program. 


* Change the TYPE to a compatible and less restrictive value. For example, change 
the TYPE from *NAME to *CHAR. 


* Change the MAX value to greater than 1. 
* Change the PASSATR and VARY values. 
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The following changes can be made to the command definition statements 
depending on what was specified in the CL procedure or program in which the 
command is used: 


* Remove a parameter. 

* Change the RANGE and REL values to be more restrictive. 
* Remove special values. 

* Decrease the number of elements allowed in a list. 


* Change the TYPE value to be more restrictive or incompatible with the original 
TYPE value. For example, change the TYPE value from *CHAR to *NAME or 
change *PNAME to *CHAR. 


* Add a SNGVAL parameter that was previously a list item. 
* Change the name of an optional parameter. 

* Remove a value from a list of values. 

* Increase the number of required list items. 

* Change a SNGVAL parameter to a SPCVAL parameter. 

* Change a simple list to a mixed list of like elements. 

* Change an optional parameter to a constant. 

* Change RTNVAL from *YES to *NO, or from *NO to *YES. 
* Change case value from *MIXED to *MONO. 


The following changes can be made to the command definition statements, but 
may cause the procedure or program that uses the command to function 
differently: 


* Change the meaning of a value. 

* Change the default value. 

* Change a SNGVAL parameter to a SPCVAL parameter. 
* Change a value to a SNGVAL parameter. 

* Change a list to a list within a list. 

* Change case value from *MIXED to *MONO. 


The following changes to the command definition statements require that the 
procedures or program using the command be re-created. 


* Addition of a new required parameter. 

* Removal of a required parameter. 

* Changing the name of a required parameter. 

* Changing a required parameter to a constant. 

* Changing the command processing program to or from *REXX 


In addition, if you specify *LIBL as the qualifier on the name of the command 
processing program or the validity checking when the command is created or 
changed, you can move the command processing program or the validity checking 
to another library in the library list without changing the command definition 
statements. 


Changing Command Defaults 


You can change the default value of a command keyword by using the Change 
Command Default (CHGCMDDFT) command. Refer to the CL section of the 
Programming category of the iSeries Information Center for details. The keyword 
must have an existing default in order to allow a change to a new default value. 
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You can change either an IBM-supplied command or a user-written command. You 
must use caution when changing defaults for IBM-supplied commands. The 
following are recommendations for changing defaults: 


1. Use the Create Duplicate Object (CRTDUPOBJ) command to create a duplicate 
of the IBM-supplied command that you want to change in a user library. This 
allows other users on the system to use the IBM-supplied defaults if necessary. 


Use the Change System Library List (CHGSYSLIBL) command to move the user 
library ahead of QSYS or any other system-supplied libraries in the library list. 
This will allow the user to use the changed command without using the library 
qualifier. 


Changes to commands that are needed on a system-wide basis should be made 
in a user library. Additionally, you should add the user library name to the 
QSYSLIBL system value ahead of QSYS. The changed command is used 
system-wide. If you need to run an application that uses the IBM-supplied 
default, do so by using the Change System Library List (CHGSYSLIBL) 
command. Doing this removes the special library or library-qualify to the 
affected commands. 


2. Installing a new release of a licensed program replaces all IBM-supplied 
commands for the licensed program on the machine. You should use a CL 
program to make changes to commands when installing a new release. This 
way you can run the CL program to duplicate the new commands to pick up 
any new keywords and make the command default changes. 


If an IBM-supplied command has new keywords, a copy of the command from 
a previous release may not run properly. 


The following is an example of a CL program that is used to delete the old 
version and create the new changed command: 
PGM 
DLTCMD USRQSYS/SIGNOFF 
CRTDUPOBJ OBJ(SIGNOFF) FROMLIB(QSYS) OBJTYPE(*CMD) + 
TOLIB(USRQSYS) NEWOBJ(*SAME) 
CHGCMDDFT CMD(USRQSYS/SIGNOFF) NEWDFT('LOG(*LIST) ') 


Repeat the DLTCMD, CRTDUPOBJ and CHGCMDDFT for each 
command you want changed 


ENDPGM 


You can track changes you make to CL command defaults for use when you install 
a new release. To track changes, register an exit program for exit point 
QIBM_QCA_RTV_COMMAND. The exit program is called when you run the 
CHGCMDDFT command. One of the parameters passed to the exit program is the 
command string that is being run. You can save the command string to a source 
file and then compile the source file into a CL program. Finally, you use this 
program to reproduce the changes you have made to command defaults during 
the previous release. For more information, see the Command Analyzer Retrieve 
exit program description in the APIs section of the Programming category of the 
iSeries Information Center. 


The following steps can be used to build the NEWDFT command string for the 
CHGCMDDFT command. The USROSYS/CRTCLPGM command is used in this 
example. 


1. Create a duplicate copy of the command to be changed in a user library with 
the following command: 
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CRTDUPOBJ OBJ(CRTCLPGM) FROMLIB(QSYS) OBJTYPE(*CMD) + 
TOLIB(USRQSYS) NEWOBJ(*SAME) 

2. Enter the command name to be changed in a source file referred to by the 
Source Entry Utility (GEU). 

3. Press F4 to call the command prompter. 

4. Enter any new default values for the keywords you want changed. In this 
example, AUT(*EXCLUDE) and TEXT('Isn''t this nice text') is entered. 

5. Required keywords cannot have a default value; however, in order to get the 
command string in the source file, a valid value must be specified for each 
required keyword. Specify PGM1 for the PGM parameter. 

6. Press the Enter key to put the command string into the source file. The 
command string returned would look like this: 
USRQSYS/CRTCLPGM PGM(PGM1) AUT(*EXCLUDE) + 
TEXT('Isn''t this nice text') 

7. Remove the required keywords from the command string: 


USRQSYS/CRTCLPGM AUT(*EXCLUDE) + 
TEXT('Isn''t this nice text') 


Remember that you may change only parameters, elements, or qualifiers that 
have existing default values. Specifying a value for a parameter, element, or 
qualifier that does not have an existing default value makes no default 
changes. 


8. Insert the CHGCMDDEFT at the beginning as shown in the example below: 


CHGCMDDFT USRQSYS/CRTCLPGM AUT(*EXCLUDE) + 
TEXT('Isn''t this nice text') 
9. You must quote the input for the NEWDFT keyword as shown in the example 

below: 
CHGCMDDFT USRQSYS/CRTCLPGM 'AUT(*EXCLUDE) + 
TEXT('Isn''t this nice text')' 

10. Since there are embedded apostrophes in the NEWDFT value, you must 
double them for the process to run properly: 
CHGCMDDFT USRQSYS/CRTCLPGM 'AUT(*EXCLUDE) + 
TEXT(''Isn''''t this nice text'')' 

11. Now if you press F4 to call the command prompter, then F11 to request 
keyword prompting, you will see the following display: 


Command. ........ +. : = 4€MD R_  CRTICLPGM 
EVRA ae. at eS we cas USRQSYS 
New default parameter string: NEWDFT R _'AUT(*EXCLUDE) 


TEXT(''Isn''''t this nice text'')' 
12. Now if you press the Enter key, the CHGCMDDFT command string is: 


CHGCMDDFT CMD(USRQSYS/CRTCLPGM) NEWDFT('AUT(*EXCLUDE) + 
TEXT(''Isn''''t this nice text'')') 


13. Press F1 to exit SEU and create and run the CL program or procedure. 


14. The USROSYS/CRTCLPGM will have default values of *EXCLUDE for AUT and 
'Isn''t this nice text' for TEXT. 


Example 1 


To provide a default value of *NOMAX for the MAXMBRS keyword of command 
CRTPF, do the following: 


CRTPF FILE(FILE1) RCDLEN(96) MAXMBRS (1) 


CHGCMDDFT CMD(CRTPF) NEWDFT( 'MAXMBRS (*NOMAX) ') 
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Example 2 
To provide a default value of 10 for the MAXMBRS keyword of the command 
CRTPF, do the following: 


CRTPF FILE(FILE1) RCDLEN(96) MAXMBRS (*NOMAX) 


CHGCMDDFT CMD(CRTPF) NEWDFT('MAXMBRS(10) ') 


Example 3 

The following allows you to provide a default value of LIBOO1 for the first qualifier 
of the SRCFILE keyword and FILE001 for the second qualifier of the SRCFILE 
keyword for the command CRTCLPGM. The AUT keyword now have a default 
value of *EXCLUDE. 


CRTCLPGM PGM(PROGRAM1) SRCFILE(*LIBL/QCMDSRC) 


CHGCMDDFT CMD(CRTCLPGM) + 
NEWDFT ('SRCFILE(LIBQO1/FILEQ01) AUT(*EXCLUDE) ') 


Example 4 
The following provides a default value of ‘Isn’t this print text’ for the PRTTXT 


keyword of the command CHGJOB. Since the NEWDFT keyword has embedded 
apostrophes, you must not double these apostrophes, or the process will not run 
correctly. 


CHGJOB PRTTXT('Isn''t this print text') 


CHGCMDDFT CMD(CHGJOB) + 
NEWDFT('PRTTXT(''Isn''''t this print text'')') 


Example 5 

The following provides a default value of QGPL for the first qualifier (library 
name) of the first list item of the DTAMBRS keyword for the command CRTLF. 
The new default value for the second list item of the DIAMBRS keyword (member 
name) is MBR1. 


CRTLF FILE(FILE1) DTAMBRS(*ALL) 


CHGCMDDFT CMD(CRTLF) + 
NEWDFT ('DTAMBRS((QGPL/*N (MBR1)))') 


Since *ALL is a SNGVAL (single value) for the entire DIAMBRS list, the defaults 
of *CURRENT for the library name and *NONE for the member name do not 
show up on the original command prompt display. The defaults *CURRENT and 
*NONE can be changed to a new default value but do not show up on the original 
prompt display because of the *ALL single value for the entire DITAMBRS list. 


Example 6 
Create a command that will display the spool files for a job: 


CRTDUPOBJ OBJ(WRKJOB) FROMLIB(QSYS) + 
TOLIB(MYLIB) NEWOBJ(WRKJOBSPLF) 
WRKJOBSPLF OPTION(*SPLF) 


CHGCMDDFT CMD(MYLIB/WRKJOBSPLF) + 
NEWDFT ('OPTION(*SPLF) ') 
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Writing a Command Processing Program or Procedure 


A command processing program (CPP) can be a CL or HLL program, or a REXX 
procedure. Programs written in CL or HLL can also be called directly with the 
CALL CL command. REXX procedures can be called directly using the Start REXX 
Procedure (STRREXPRC) command. The command processing program does not 
need to exist when the Create Command (CRTCMD) command is run. If *LIBL is 
used as the library qualifier, the library list is used to find the command processing 
program when the created command is run. 


Messages issued as a result of running the command processing program can be 
sent to the job message queue and automatically displayed or printed. You can 
send displays to the requesting display station. 

Notes: 


1. The parameters defined on the command are passed individually in the order 
they were defined (the PARM statement order). 


2. Decimal values are passed to HLL and CL programs as packed decimal values 
of the length specified in the PARM statement. 


3. Character, name, and logical values are passed to HLL and CL programs as a 
character string of the length defined in the PARM statement. 


Writing a CL or HLL Command Processing Program 


shows the relationship between the Create Command 
(CRTCMD) command, the command definition statements, and the command 
processing program. 


Chapter 9. Defining Commands 337 


CRTCMD CMD(DSPORD) PGM(DSPORDPGM) 


Definition for DSPORD Command: 


CMD ‘DisplayOrder’ 
PARM KWD (ORDER) + 
TYPE (*DEC )+ 
LEN (6 0) + 
RANGE (100000 600000) + 
PROMPT (’Ordernumber: ’) 


Vv 
Command Processing Program for DSPORD Command (DSPORDPGM) : 


PGM (&0RDER) 
DCL &ORDER + 
TYPE (*DEC) + 
LEN (6 0) 
RANGE (100000 600000) + 
PROMPT (’Ordernumber: ’) 


RBAFN542-0 


Figure 15. Command Relationships for CL and HLL 


If the command processing program is a program written in CL, the variables that 
receive the parameter values must be declared to correspond to the type and 
length specified for each PARM statement. The following shows this 
correspondence. (Note the declare for the parameter ORDER in Figure 151) 


PARM Statement PARM Statement Declared Variable Declared Variable 
Type Length Type Length 
*DEC xy! *DEC xy! 
*LGL 1 *LGL 1 
*CHAR n *CHAR <n? 
*NAME n *CHAR <n? 
*CNAME n *CHAR <n? 
*SNAME n *CHAR <n? 
*GENERIC n *CHAR <n? 
*CMDSTR n *CHAR <n? 
*DATE 7 *CHAR 7 
*TIME 6 *CHAR 6 
*INT2 n *CHAR 2 
*INT4 n *CHAR 4 
*UINT2 n *CHAR 2 
*UINT4 n *CHAR 4 
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PARM Statement PARM Statement Declared Variable Declared Variable 


Type Length Type Length 
: x equals the length and y is the number of decimal positions. 
2 For character variables, if the length of the value passed is greater than the length 


declared, the value is truncated to the length declared. If RTNVAL(*YES) is 
specified, the length declared must equal the length defined on the PARM 


statement. 


A program written in CL used as a command processing program can process 
binary values (such as *INT2 or *INT4). The program should receive these values 
as character fields. The binary built-in function (YBINARY) can be used to convert 


them to decimal values. 


The difference between *INT2 or *INT4 and *UINT2 or *UINT4 is that the *INT 2 
and *INT4 types are signed integers and the *UINT2 and *UINT4 types are 
unsigned integers. The default value for both *UINT2 and *UINT4 is 0. The 
*UINT2 and *UINT4 types have the same restrictions as the *INT and *INT4 types. 


Note: The “BINARY built-in function is for use with signed integers. There is no 
corresponding function for unsigned integers. 


Writing a REXX Command Processing Procedure 


Figure 14 shows the relationship between the Create Command (CRTCMD) 
command, the command definition statements, and the command processing 
procedure for REXX. 


CALL PGM(PGMA) PARM('ADDLIBLE LIB(MYLIB)' 19) 


PGM PARM(&STRING &LENGTH) /* PGMA */ 
DCL &STRING *CHAR LEN(3000) 
DCL &LENGTH *DEC LEN(15 5) 

> QCMDEXC 
CALL PGM(QCMDEXC) PARM(&STRING &LENGTH) 

< 
: CHGLIBL... 
END . 
RBAFN500-0 


Figure 16. Command Relationships for REXX 
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Writing a Validity Checking Program 


If you write a validity checking program for your command, specify the name of 
the validity checking program on the VLDCKR parameter on the Create Command 
(CRTCMD) command. The program does not have to exist when the CRTCMD 
command is run. If *LIBL is used as the library qualifier, the library list is used to 
find the validity checking program when the created command is run. 


The following are two considerations for validity checking programs: 


* The validity checking program is called only if the command syntax is correct. 
All parameters are passed to the program the same as they are passed to a 
command processing program. 


* You should not use the validity checking program to change parameter values 
because the changed values are not always passed to the command processing 
program. 


The remainder of this section describes how to send messages from a validity 
checking program that is written in CL. 


If the validity checking program detects an error, it should send a diagnostic 
message to the previous call and then send escape message CPFO0002. For example, 
if you need a message saying that an account number is no longer valid, you add 
a message description similar to the following to a message file: 
ADDMSGD MSG('Account number &2 no longer valid') + 

MSGID(USROO12) + 

MSGF(QGPL/ACTMSG) + 

SEV(40) + 

FMT((*CHAR 4) (*CHAR 6)) 


Note that the substitution variable &1 is not in the message but is defined in the 
FMT parameter as 4 characters. &1 is reserved for use by the system and must 
always be 4 characters. If the substitution variable &1 is the only substitution 
variable defined in the message, you must ensure that the fourth byte of the 
message data does not contain a blank when you send the message. 


This message can be sent to the system by specifying the following in the validity 
checking: 


SNDPGMMSG = MSGID(USRO@12) MSGF(QGPL/ACTMSG) + 
MSGDTA('0000' || &ACCOUNT) MSGTYPE(*DIAG) 


After the validity checking has sent all the necessary diagnostic messages, it should 
then send message CPF0002. The Send Program Message (GNDPGMMSG) 
command to send message CPF0002 looks like this: 


SNDPGMMSG = MSGID(CPF0Q02) MSGF(QCPFMSG) + 
MSGTYPE (*ESCAPE) 


When the system receives message CPF0002, it sends message CPF0001 to the 
calling program to indicate that errors have been found. 


Message CPD0006 has been defined for use by the user-defined validity checking 
programs. An immediate message can be sent in the message data. Note in the 


following example that the message must be preceded by four character zeros. 


The following shows an example of a validity checking program: 
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PGM PARM(&PARMO1) 

DCL VAR(&PARMO1) TYPE(*CHAR) LEN(10) 

IF COND(&PARMQ1 *EQ 'ERROR') THEN(DO) 

SNDPGMMSG MSGID(CPD0006) MSGF(QCPFMSG) + 
MSGDTA('0000 DIAGNOSTIC MESSAGE FROM USER-DEFINED + 
VALIDITY CHECKER INDICATING THAT PARMO1 IS IN ERROR.') + 


MSGTYPE(*DIAG) 
SNDPGMMSG MSGID(CPFO0Q2) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) 
ENDDO 
ELSE 
ENDPGM 


Examples of Defining and Creating Commands 


This section contains examples of defining and creating commands. 


Calling Application Programs 


You can create commands to call application programs. If you create a command to 
call an application program, OS/400 performs validity checking on the parameters 
passed to the program. However, if you use the CALL command to call an 
application program, the application program must perform the validity checking. 


For example, a label writing program (LBLWRT) writes any number of labels for a 
specific customer on either 1- or 2-part forms. When the LBLWRT program is run, 
it requires three parameters: the customer number, the number of labels, and the 
type of form to be used (ONE or TWO). 


If the program were called directly from the display, the second parameter would 
be in the wrong format for the program. A numeric constant on the CALL 
command is always 15 digits with 5 decimal positions, and the LBLWRT program 
expects a 3-digit number with no decimal positions. A command can be created 
that provides the data in the format required by the program. 


The command definition statements for a command to call the LBLWRT program 
are: 
CMD PROMPT('Label Writing Program') 
PARM KWD(CUSNBR) TYPE(*CHAR) LEN(5) MIN(1) + 
PROMPT ('Customer Number') 
PARM KWD(COUNT) TYPE(*DEC) LEN(3) DFT(20) RANGE(10 150) + 
PROMPT('Number of Labels') 
PARM KWD(FRMTYP) TYPE(*CHAR) LEN(3) DFT('TWO') RSTD(*YES) + 
SPCVAL(('ONE') ('TWO') ('1' 'ONE') ('2' 'TWO')) + 
PROMPT ('Form Type') 


For the second parameter, COUNT, a default value of 20 is specified and the 
RANGE parameter allows only values from 10 to 150 to be entered for the number 
of labels. 


For the third parameter, FRMTYP, the SPCVAL parameter allows the display 
station user to enter 'ONE', 'TWO', '1', or '2' for this parameter. The program 
expects the value 'ONE' or 'TWO'; however, if the display station user enters '1' or 
'2', the command makes the necessary substitution for the FRMTYP parameter. 


The command processing program for this command is the application program 
LBLWRT. If the application program were an RPG for OS/400 program, the 
following specifications would be made in the program to receive the parameters: 
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*ENTRY = PLIST 
PARM CUST 5 
PARM COUNT 30 
PARM FORM 3 


The CRTCMD command is: 
CRTCMD CMD(LBLWRT) PGM(LBLWRT) SRCMBR(LBLWRT) 


Substituting a Default Value 


You can create a command that provides defaults for an IBM-supplied command 
and reduces the entries that the display station user must make. For example, you 
could create a Save Library on Tape (SAVLIBTAP) command that initializes a tape 
and saves a library on the tape device TAPE1. This command provides defaults for 
the standard Save Library (SAVLIB) command parameters and requires the display 
station user to specify only the library name. 


The command definition statements for the SAVLIBTAP command are: 


CMD PROMPT('Save Library to Tape') 
PARM KWD(LIB) TYPE(*NAME) LEN(10) MIN(1) + 
PROMPT('Library Name') 


The command processing program is: 


PGM PARM(&LIB) 

DCL &LIB TYPE(*CHAR) LEN(10) 
INZTAP DEV(TAPE1) CHECK(*NO) 
SAVLIB LIB(&LIB) DEV(TAPE1) 
ENDPGM 


The CRTCMD command is: 
CRTCMD CMD(SAVLIBTAP) PGM(SAVLIBTAP) SRCMBR(SAVLIBTAP) 


Displaying an Output Queue 


You can create a command to display an output queue that defaults to display the 
output queue PGMR. The following command, DSPOQ, also allows the display 
station user to display any queue on the library list and provides a print option. 


The command definition statements for the DSPOQ command are: 


CMD PROMPT ('WRKOUTQ.-Default to PGMR') 

PARM KWD(OQUTQ) TYPE(*NAME) LEN(10) DFT(PGMR) + 
PROMPT('Output queue') 

PARM KWD(OQUTPUT) TYPE(*CHAR) LEN(6) DFT(*) RSTD(*YES) 
VALUES(* *PRINT) PROMPT('Output') 


The RSTD parameter on the second PARM statement specifies that the entry can 
only be one of the list of values. 


The command processing program for the DSPOQ command is: 


PGM PARM(&0UTQ &OUTPUT) 

DCL 80UTQ TYPE(*CHAR) LEN(10) 

DCL 8O0UTPUT TYPE(*CHAR) LEN(6) 

WRKOUTQ OUTQ(*LIBL/&0UTQ) OUTPUT (&OUTPUT) 
ENDPGM 


The CRTCMD command is: 
CRTCMD CMD(DSP0Q) PGM(DSP0Q) SRCMBR(DSP0Q) 
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The following command, DSPOQI1, is a variation of the preceding command. This 
command allows the work station user to enter a qualified name for the output 
queue name, and the command defaults to *LIBL for the library name. 


The command definition statements for the DSPOQ1 command are: 


CMD PROMPT('WRKOUTQ.-Default to PGMR') 

PARM  KWD(OUTQ) TYPE(QUAL1) + 
PROMPT('Output queue:') 

PARM  KWD(OUTPUT) TYPE(*CHAR) LEN(6) RSTD(*YES) + 
VALUES (* *PRINT) DFT(*) + 
PROMPT (‘Output ') 

QUAL1: QUAL TYPE(*NAME) LEN(10) DFT(PGMR) 
QUAL TYPE(*NAME) LEN(10) DFT(*LIBL) + 
SPCVAL(*LIBL) 


The QUAL statements are used to define the qualified name that the user can enter 
for the OUTQ parameter. If the user does not enter a name, *LIBL/PGMR is used. 
The SPCVAL parameter is used because any library name must follow the rules for 
a valid name (for example, begin with A through Z), and the value *LIBL breaks 
these rules. The SPCVAL parameter specifies that if *LIBL is entered, OS/400 is to 
ignore the name validation rules. 


The command processing program for the DSPOQ1 command is: 


PGM PARM(&0UTQ &OUTPUT) 

DCL 80UTQ TYPE(*CHAR) LEN(20) 

DCL 80BJNAM TYPE(*CHAR) LEN(10) 

DCL &LIB TYPE(*CHAR) LEN(10) 

DCL 8O0UTPUT TYPE(*CHAR) LEN(6) 

CHGVAR &8OBJNAM %SUBSTRING(&OUTQ 1 10) 
CHGVAR &LIB %SUBSTRING(&OUTQ 11 10) 
WRKOUTQ OUTQ(&LIB/&0BJNAM) OUTPUT (&0UTPUT) 
ENDPGM 


Because a qualified name is passed from a command as a 20-character variable, the 
substring built-in function (%SUBSTRING or %SST) must be used in this program 
to put the qualified name in the proper CL syntax. 


Displaying Messages from IBM Commands More Than Once 


The CLROUTO command issues the completion message CPF3417, which describes 
the number of entries deleted, the number not deleted, and the name of the output 
queue. If the CLROUTQ command is run within a CPP, the message is still issued 
but it becomes a detailed message because it is not issued directly by the CPP. For 
example, if a user-defined CLROUTQ command was issued from the Programmer 
Menu, the message would not be displayed. You can, however, receive an IBM 
message and reissue it from your CPP. 


For example, you create a command named CQ2 to clear the output queue 
QPRINT2. 


The command definition statements for the CQ2 command are: 
CMD PROMPT (‘Clear QPRINT2 output queue') 


The CRTCMD command is: 
CRTCMD CMD(CQ2) PGM(CQ2) 


The CPP, which receives the completion message and displays it, is as follows: 
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PGM /* Clear QPRINT2 output queue CPP */ 

DCL &MSGID TYPE(*CHAR) LEN(7) 

DCL &MSGDTA TYPE(*CHAR) LEN(100) 

CLROUTQ QPRINT2 

RCVMSG MSGID(&MSGID) MSGDTA(&MSGDTA) MSGTYPE(*COMP) 

SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGDTA(&MSGDTA) MSGTYPE(*COMP) 
ENDPGM 


The MSGDTA length for message CPF3417 is 28 bytes. However, by defining the 
variable &MSGDTA as 100 bytes, the same approach can be used on most 
messages because any unused positions are ignored. 


Creating Abbreviated Commands 


Example 1 

You can create your own abbreviated commands to simplify IBM-supplied 
commands or to restrict the parameters allowed for users. For example, to allow 
users the ability to change only the printer device parameter, you can create your 
own Change Job (CJ) command. Following are three steps to create and implement 
your own CJ command: 

* Step one: Command definition source statements 


CMD PROMPT('Change Job') 
PARM KWD(PRTDEV) + 
TYPE(*NAME) + 
LEN(10) + 
SPCVAL(*SAME *USRPRF *SYSVAL *WRKSTN) + 
PROMPT ('Printer Device') 


* Step two: Processing program 


PGM PARM(&PRTDEV) 

DCL VAR(&PRTDEV) TYPE(*CHAR) LEN(10) 
CHGJOB PRTDEV(&PRTDEV) 

ENDPGM 


* Step three: CRTCMD command 
CRTCMD CMD(CJ) PGM(CJ) SRCMBR(CJ) 


Example 2 
You could create an abbreviated command called DW1 to start the printer writer 
W1. 


The command definition statement is: 
CMD /* Start printer writer command */ 


The command processing program is: 


PGM 
STRPRTWTR DEV(QSYSPRT) OUTQ(QPRINT) WTR(W1) 
ENDPGM 


The CRTCMD command is: 
CRTCMD CMD(DW1) PGM(DW1) SRCMBR(DW1) 


Deleting Files and Source Members 


You can create a command to delete files and their corresponding source members 
in QDDSSRC. 


The command definition statements for the command named DFS are: 
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CMD PROMPT('Delete File and Source') 
PARM KWD(FILE) TYPE(*NAME) LEN(10) PROMPT('File Name') 


The command processing program is written assuming that the name of the file 
and the source file member are the same. The program also assumes that both the 
file and the source file are on the library list. If the program cannot delete the file, 
an information message is sent and the command attempts to remove the source 
member. If the source member does not exist, an escape message is sent. 


The command processing program is: 


PGM PARM(&FILE) 
DCL &FILE TYPE(*CHAR) LEN(10) 
DCL &MSGID TYPE(*CHAR) LEN(7) 
DCL &MSGDTA TYPE(*CHAR) LEN(80) 
DCL &SRCFILE TYPE(*CHAR) LEN(10) 
MONMSG MSGID(CPFO000) EXEC(GOTO ERROR) /* CATCH ALL */ 
DLTF &FILE 
MONMSG MSGID(CPF2105) EXEC(DO) /* NOT FOUND »/ 
RCVMSG MSGTYPE(*EXCP) MSGID(&MSGID) MSGDTA(&MSGDTA) 
SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGTYPE(*INFO) + 
MSGDTA(&MSGDTA) 
GOTO TRYDDS 
ENDDO 
RCVMSG MSGTYPE(*COMP) MSGID(&MSGID) MSGDTA(&MSGDTA) 
/* DELETE FILE COMPLETED */ 
SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGTYPE(*COMP) + 
MSGDTA(&MSGDTA) /* TRY IN QDDSSRC FILE */ 
TRYDDS: | CHKOBJ QDDSSRC OBJTYPE(*FILE) MBR(&FILE) 
RMVM QDDSSRC MBR(&FILE) 
CHGVAR &SRCFILE 'QDDSSRC' 
GOTO END 
END: RCVMSG MSGTYPE(*COMP) MSGID(&MSGID) MSGDTA(&MSGDTA) 
/* REMOVE MEMBER COMPLETED »/ 
SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGTYPE(*COMP) + 
MSGDTA(&MSGDTA) 
RETURN 
ERROR: | RCVMSG MSGTYPE(*EXCP) MSGID(&MSGID) MSGDTA(&MSGDTA) 
/* ESCAPE MESSAGE */ 
SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) + 
MSGDTA (&MSGDTA) 
ENDPGM 


Deleting Program Objects 


You can create a command to delete HLL programs and their corresponding source 
members. 


The command definition statements for the command named DP$S are: 


CMD PROMPT (‘Delete Program and Source') 
PARM KWD(PGM) TYPE(*NAME) LEN(10) PROMPT('Program Name ') 


The command processing program is written assuming that the name of the 
program and the source file member are the same. Additionally, you have to use 
the IBM-supplied source files of QCLSRC, QRPGSRC, and QCBLSRC. The program 
also assumes that both the program and the source file are on the library list. If 
you cannot open the program, the system sends an information message, and the 
command attempts to remove the source member. If the source member does not 
exist, the system sends an escape message. The command processing program is: 
PGM PARM(&PGM) 

DCL &PGM TYPE(*CHAR) LEN(10) 


DCL &MSGID TYPE(*CHAR) LEN(7) 
DCL &MSGDTA TYPE(*CHAR) LEN(80) 
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DCL &SRCF 
MONMSG MS 
DLTPGM &P 
MONMSG MS 
RCVMSG MS 
SNDPGMMSG 
MSG 
GOTO TRYC 
ENDDO 
RCVMSG MS 
/* DE 
SNDPGMMSG 
MSGD 
TRYCL: 


TRYRPG: 


TRYCBL: 


TRYNXT: 


END: 


ERROR: 
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ILE TYPE(*CHAR) LEN(10) 

GID(CPFO000) EXEC(GOTO ERROR) /* CATCH ALL */ 
GM 

GID(CPF2105) EXEC(DO) /* NOT FOUND*/ 
GTYPE(*EXCP) MSGID(&MSGID) MSGDTA(&MSGDTA) 
MSGID(&MSGID) MSGF(QCPFMSG) MSGTYPE(*INFO) + 
DTA(&MSGDTA) 

L /* TRY TO DELETE SOURCE MEMBER */ 


GTYPE(*COMP) MSGID(&MSGID) MSGDTA(&MSGDTA) 
LETE PROGRAM COMPLETED */ 
MSGID(&MSGID) MSGF(QCPFMSG) MSGTYPE(*COMP) + 
TA(&MSGDTA) /* TRY IN QCLSRC */ 
CHKOBJ QCLSRC OBJTYPE(*FILE) MBR(&PGM) 
MONMSG MSGID(CPF9815) EXEC(GOTO TRYRPG) /* NO CL MEMBER */ 
RMVM QCLSRC MBR(&PGM) 
CHGVAR &SRCFILE 'QCLSRC' 
GOTO END 
/* TRY IN QRPGSRC FILE */ 
CHKOBJ QRPGSRC OBJTYPE(*FILE) MBR(&PGM) 
MONMSG MSGID(CPF9815) EXEC(GOTO TRYCBL) /* NO RPG MEMBER */ 
RMVM QRPGSRC MBR(&PGM) 
CHGVAR &SRCFILE 'QRPGSRC' 
GOTO END 
/* TRY IN QCBLSRC FILE */ 
CHKOBJ QCBLSRC OBJTYPE(*FILE) MBR(&PGM) 
/* ON LAST SOURCE FILE LET CPFOQ0@ OCCUR FOR A NOT FOUND + 
CONDITION / 
RMVM QCBLSRC MBR(&PGM) 
CHGVAR &SRCFILE 'QCBLSRC' 
GOTO END 
/* INSERT ANY ADDITIONAL SOURCE FILES ~/ 
/* ADD MONMSG AFTER CHKOBJ IN TRYCBL AS WAS + 
DONE IN TRYCL AND TRYRPG x/ 
RCVMSG MSGTYPE(*COMP) MSGID(&MSGID) MSGDTA(&MSGDTA) 
/*REMOVE MEMBER COMPLETED ~/ 
SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGTYPE(*COMP) + 
MSGDTA(&MSGDTA) 
RETURN 
RCVMSG MSGTYPE(*EXCP) MSGID(&MSGID) MSGDTA(&MSGDTA) 
/* ESCAPE MESSAGE */ 
SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) + 
MSGDTA(&MSGDTA) 
ENDPGM 
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Debugging ILE Programs 


Debugging allows you to detect, diagnose, and eliminate errors in a program. You 
can debug your ILE programs by using the ILE source debugger. This chapter 
describes how to use the ILE source debugger. 


This chapter describes how to: 

* Prepare your ILE program for debugging 

* Start a debug session 

* Add and remove programs from a debug session 

* View the program source from a debug session 

* Set and remove conditional and unconditional breakpoints 
* Step through a program 

* Display the value of variables 

* Change the value of variables 

* Display the attributes of variables 

* Equate a shorthand name to a variable, expression, or debug command. 


While debugging and testing your programs, ensure that your library list is 
changed to direct the programs to a test library containing test data so that any 
existing real data is not affected. 


You can prevent database files in production libraries from being modified 
unintentionally by using one of the following commands: 


* Use the Start Debug (STRDBG) command and retain the default *NO for the 
UPDPROD parameter. 


* Use the Change Debug (CHGDBG) command. 


See the CL section of the Programming category of the iSeries Information Center 
for more information. 


See book, Chapter 10, "Debugging Considerations”, for more 
information on the ILE source debugger (including authority required to debug a 
program or service program and the effects of optimization levels). 


The ILE Source Debugger 


The ILE source debugger is used to detect errors in and eliminate errors from 
program objects and service programs. You can use the source debugger to: 


* Debug any ILE CL or mixed ILE language application 

* Monitor the flow of a program by using the debug commands while the 
program is running. 

* View the program source 

* Set and remove conditional and unconditional breakpoints 

* Step through a specified number of statements 

* Display or change the value of variables 
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* Display the attributes of a variable 


When a program stops because of a breakpoint or a step command, the applicable 
module object’s view is shown on the display at the point where the program 
stopped. At this point you can enter more debug commands. 


Before you can use the source debugger, you must use the debug options 
(DBGVIEW) when you create a module object or program object using Create CL 
Module (CRTCLMOD) or Create Bound CL (CRTBNDCL). After you set the 
breakpoints or other ILE source debugger options, you can call the program. 


Debug Commands 


Many debug commands are available for use with the ILE source debugger. The 
debug commands and their parameters are entered on the debug command line 
displayed on the bottom of the Display Module Source and Evaluate Expression 
displays. These commands can be entered in upper case, lower case, or mixed case. 


Note: The debug commands entered on the source debugger command line are 
not CL commands. 


[able ol summarizes these debug commands. The online help for the ILE source 
debugger describes the debug commands and explains their allowed abbreviations. 


Table 9. ILE source debugger commands 


Debug 

Command Description 

ATTR Permits you to display the attributes of a variable. The attributes are 
the size and type of the variable as recorded in the debug symbol table. 

BREAK Permits you to enter either an unconditional or conditional breakpoint 
at a position in the program being tested. Use BREAK position WHEN 
expression to enter a conditional breakpoint. 

SBREAK Permits you to enter a service entry point at a position in the program 
being tested. A service entry point is a type of breakpoint established in 
a program to facilitate the system debugger in gaining control of a 
spawned job. The breakpoint is only signaled when the job within 
which the service entry point was hit is not currently under debug. 

CLEAR Permits you to remove conditional and unconditional breakpoints. 

DISPLAY Allows you to display the names and definitions assigned by using the 
EQUATE command. It also allows you to display a different source 
module than the one currently shown on the Display Module Source 
display. The module object must exist in the current program object. 

EQUATE Allows you to assign an expression, variable, or debug command to a 
name for shorthand use. 

EVAL Allows you to display or change the value of a variable or to display 
the value of expressions. 

QUAL Allows you to define the scope of variables that appear in subsequent 
EVAL commands. 

STEP Allows you to run one or more statements of the program being 
debugged. 

FIND Searches the module currently displayed for a specified line-number or 
string or text. 

UP Moves the displayed window of source towards the beginning of the 
view by the amount entered. 
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Table 9. ILE source debugger commands (continued) 


Debug 

Command Description 

DOWN Moves the displayed window of source towards the end of the view by 
the amount entered. 

LEFT Moves the displayed window of source to the left by the number of 
characters entered. 

RIGHT Moves the displayed window of source to the right the number of 
characters entered. 

TOP Positions the view to show the first line. 

BOTTOM Positions the view to show the last line. 

NEXT Positions the view to the next breakpoint in the source currently 
displayed. 

PREVIOUS Positions the view to the previous breakpoint in the source currently 
displayed. 

HELP Shows the online help information for the available source debugger 
commands. 

SET Specifies if case sensitive or case insensitive searching is performed for 
all subsequent FIND requests in the current debug session. It also 
allows you to change the update production files value. 

WATCH Displays a list of the currently active watch conditions. 


Preparing a Program Object for a Debug Session 


Before you can use the ILE source debugger, you must use either the CRTCLMOD 
or CRTBNDCL command and specify the DBGVIEW option. 


For each ILE CL module object that you want to debug, you can create one of 
three views: 


¢ Root source view 
* Listing view 
e Statement view 


Using a Root Source View 
A root source view contains the source statements of the source member. 


To use the root source view with the ILE source debugger, the ILE CL compiler 
creates the root source view while the module object (*MODULE) is being created. 


Note: The module object is created by using references to locations of the source 
statements in the root source member instead of copying the source 
statements into the view. Therefore, you should not modify, rename, or 
move root source members between the creation of the module and the 
debugging of the module created from these members. 


To debug an ILE CL module object by using a root source view, use the *SOURCE 
or *ALL option on the DBGVIEW parameter for either the CRTCLMOD or 
CRTBNDCL commands. 


One way to create a root source view, is as follows: 
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CRTCLMOD 
MODULE (MYLIB/MYPGM) SRCFILE(MYLIB/QCLLESRC) SRCMBR(MYPGM) TEXT('CL Program') 
DBGVIEW(*SOURCE) 


The Create CL Module (CRTCLMOD) command with *SOURCE for the DBGVIEW 
parameter creates a root source view for module object MYPGM. 


Using a Listing View 
A listing view is similar to the source code portion of the compile listing or spool 
file produced by the ILE CL compiler. 


To debug an ILE CL module object by using a listing view, use the *LIST or *ALL 
option on the DBGVIEW parameter for either the CRTCLMOD or CRTBNDCL 
commands when you create the module. 


One way to create a listing view is as follows: 


CRTCLMOD 
MODULE (MYLIB/MYPGM) SRCFILE(MYLIB/QCLLESRC) SRCMBR(MYPGM) TEXT('CL Program') 
DBGVIEW(*LIST) 


Using a Statement View 

A statement view does not contain any CL source data. However, breakpoints can 
be added by using procedure names and statement numbers found in the compiler 
listing. To debug an ILE CL module object using a statement view, you need a 
copy of the compiler listing. 


Note: No data is shown in the Display Module Source display when a statement 
view is used to debug an ILE CL module object. 


To debug an ILE CL module object by using a statement view, use the *STMT, 
*SOURCE, *LIST, or *ALL option on the DBGVIEW parameter for either the 
CRTCLMOD or CRTBNDCL commands when you create the module. 


One way to create a statement view is as follows: 


CRTCLMOD 
MODULE (MYLIB/MYPGM) SRCFILE(MYLIB/QLSRC) SRCMBR(MYPGM) TEXT('CL Program’) 
DBGVIEW(*STMT) 


Starting the ILE Source Debugger 


After you create the debug view, you can begin debugging your application. 


To start the ILE source debugger, use the Start Debug (STRDBG) command. Once 
the debugger is started, it remains active until you enter the End Debug 
(ENDDBG) command. 


Initially, you can add as many as twenty (20) program objects and twenty (20) 
service programs to a debug session. Do this by using the Program (PGM) and 
Service Program (SRVPGM) parameters on the STRDBG command. The program 
objects can be any combination of ILE or original program model (OPM) programs. 
To start a debug session with three program objects, type: 


STRDBG PGM(*LIBL/MYPGM1 *LIBL/MYPGM2 *LIBL/MYPGM3) SRVPGM(*LIBL/SRVPGM1 *LIBL/SRVPGM2) 
DBGMODSRC (*YES) 


Note: You must have *CHANGE authority to a program object to add it to a 
debug session. 
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After entering the STRDBG command, the Display Module Source display appears 
for ILE program objects. The first module object bound to the program object with 
debug data is shown. 


The option to use the ILE source debugger to debug OPM programs exists for 
users. OPM programs contain source debug data when created. Do this only by 
specifying the OPTION(*SRCDBG) parameter of the Create CL Program 
(CRTCLPGM) command. The source debug data is actually part of the program 
object. 


To add OPM programs that are created containing source debug data to the ILE 
source debugger, use the Program (PGM) and OPM Source Level Debug 
(OPMSRC) parameters on the STRDBG command. To start a debug session with an 
OPM program created with source debug data, type: 


STRDBG PGM(*LIBL/MYOPMPGM) OPMSRC(*YES) DSPMODSRC(*YES) 


Adding Program Objects to a Debug Session 


You can add more program objects to a debug session after starting the session. 


To add ILE program objects and service programs to a debug session, use option 1 
(Add program) and type the name of the program object on the first line of the 
Work with Module List display. See fable 9 on page 248i for a list of ILE source 
debugger commands. The Work with Module List display can be accessed from the 
Display Module Source display by pressing F14 (Work with Module List). To add a 
service program, change the default program type from *PGM to *SRVPGM. There 


is no limit to the number of ILE program objects and service programs that can be 
included in a debug session at any given time. 


ie : ; > 
Work with Module List 
System: SYSTEMO1 
Type options, press enter. 
1=Add program 4=Remove program 5=Display module source 
8=Work with module breakpoints 
Opt Program/module Library Type 
L weekday2 *LIBL *PGM 
DSPWKDAY MYLIB *PGM 
DSPWKDAY *MODULE Selected 
AABP1 *MODULE 
Bottom 
Command 
===> 
F3=Exit F4=Prompt F5=Refresh F9=Retrieve  F12=Cancel 


a ee 


Figure 17. Adding an ILE Program Object to a Debug Session. When the Enter is pressed, 
program WEEKDAY2 is added to the debug session 
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- > 


Work with Module List 
System: SYSTEMO1 
Type options, press enter. 
l=Add program 4=Remove program 5=Display module source 
8=Work with module breakpoints 
Opt Program/module Library Type 
WEEKDAY2 *LIBL *PGM 
WEEKDAY2 MYLIB *PGM 
WEEKDAY2 *MODULE 
DSPWKDAY MYLIB *PGM 
DSPWKDAY *MODULE Selected 
AABP1 *MODULE 
Bottom 
Command 
===> 
F3=Exit F4=Prompt F5=Refresh F9=Retrieve F12=Cancel 


eve died WEEKDAY2 added to source debugger. 


Figure 18. Adding an ILE Program Object to a Debug Session. The information message at 
the bottom of the display shows that program WEEKDAY2 was added to the debug session. 


When you have finished adding program objects to the debug session, press F3 
(Exit) from the Work with Module List display to return to the Display Module 
Source display. You can also use option 5 (Display Module Source) to select and 
display a module. 


To add OPM programs to a debug session, use the Add Program (ADDPGM) 
command. A debug session can include up to twenty (20) OPM programs at any 
given time. You can add OPM programs that contain source debug data to the 
debug session by using option 1 (Add program) on the Work with Module List 
display. (This is true provided the debug session allows OPM source level 
debugging.) You can allow OPM source level debugging by starting the debug 
session and by using the OPMSRC parameter on the STRDBG command. If the 
OPMSRC parameter was not specified on the STRDBG command, activate OPM 
source level debugging. Do this by using the OPM Source Level Debug (OPMSRC) 
parameter on the Change Debug (CHGDBG) command. Alternately, you can 
change the value of the OPM source debug support option by using the SET debug 
command. 


Removing Program Objects from a Debug Session 


You can remove program objects from a debug session after starting the session. 
To remove ILE program objects and service programs from a debug session, use 
option 4 (Remove program), next to the program object you want to remove, on 
the Work with Module List display. See Figure 19 0n page 35d The Work with 

Module List display can be accessed from the Display Module Source display by 


pressing F14 (Work with Module List). To remove a service program, change the 
default program type from *PGM to *SRVPGM. 
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Work with Module List 
System: 
Type options, press enter. 
l=Add program 4=Remove program 5=Display module source 
8=Work with module breakpoints 


Opt Program/module Library Type 
*LIBL *PGM 
4 WEEKDAY2 MYLIB *PGM 
WEEKDAY2 *MODULE 
DSPWKDAY MYLIB *PGM 
DSPWKDAY *MODULE Selected 
AABP1 *MODULE 
Command 


===> 


F3=Exit F4=Prompt F5=Refresh F9=Retrieve  F12=Cancel 


SYSTEMO1 


Bottom 


Figure 19. Removing an ILE Program Object from a Debug Session. When the Enter key is 
pressed, program WEEKDAY2 is removed from the debug session. 


a 


Work with Module List ) 
System: SYSTEMO1 
Type options, press enter. 
l=Add program 4=Remove program 5=Display module source 
8=Work with module breakpoints 
Opt Program/module Library Type 
*LIBL *PGM 
DSPWKDAY MYLIB *PGM 
DSPWKDAY *MODULE Selected 
AABP1 *MODULE 
Bottom 
Command 
===> 
F3=Exit F4=Prompt F5=Refresh F9=Retrieve F12=Cancel 
Program WEEKDAY2 removed from source debugger. ) 


Figure 20. Removing an ILE Program Object from a Debug Session 


When you have finished removing program objects from the debug session, press 
F3 (Exit) from the Work with Module List display to return to the Display Module 
Source display. 


Note: You must have *CHANGE authority to a program to remove it from a 


debug session. 


Chapter 10. Debugging Programs 353 


To remove OPM programs from a debug session, use the Remove Program 
(RMVPGM) command. If OPM source level debugging is active, OPM programs 
that are created with source debug data may be listed on the Work with Module 
List display. You can remove these programs from the debug session by using 
option 4 (Remove program) on the Work with Module List display. 


Viewing the Program Source 


The Display Module Source display shows the source of a program object one 
module object at a time. A module object’s source can be shown if the module 
object was compiled using one of the following debug view options: 

* DBGVIEW(*ALL) 

* DBGVIEW(*SOURCE) 

* DBGVIEW(*LISTING) 


There are two methods to change what is shown on the Display Module Source 
display: 

* Change a view 

* Change a module 


When you change a view, the ILE source debugger maps to equivalent positions in 
the view you are changing to. When you change the module, the executable 
statement on the displayed view is stored in memory and is viewed when the 
module is displayed again. Line numbers that have breakpoints set are highlighted. 
When a breakpoint, step, or message causes the program to stop and the display to 
be shown, the source line where the event occurred is highlighted. 


Changing a Module Object 


You can change the module object that is shown on the Display Module Source 
display by using option 5 (Display module source) on the Work with Module List 
display. The Work with Module List display can be accessed from the Display 


Module Source display by pressing F14 (Work with Module List). The Display 
Module Source display is shown in 


To select a module object, type 5 (Display module source) next to the module 
object you want to show. 
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Display Module Source 
Program: = DSPWKDAY Library: MYLIB Module: DSPWKDAY 
24 500- CALL PGM(WEEKDAY2) PARM(&DAYOFWK) 
25 600- LE COND(&DAYOFWK *EQ 1) THEN(CHGVAR + 
26 700 VAR(&WEEKDAY) VALUE('Sunday')) 
27 800- ELSE CMD(IF COND(&DAYOFWK *EQ 2) THEN(CHGV 
28 900 VAR(&WEEKDAY) VALUE('Monday'))) 
29 1000- ELSE CMD(IF COND(&DAYOFWK *EQ 3) THEN(CHGV 
30 1100 VAR(&WEEKDAY) VALUE('Tuesday'))) 
3h 1200- ELSE CMD(IF COND(&DAYOFWK *EQ 4) THEN(CHGV 
32 1300 VAR(&WEEKDAY) VALUE('Wednesday'))) 
33 1400- ELSE CMD(IF COND(&DAYOFWK *EQ 5) THEN(CHGV 
34 1500 VAR(&WEEKDAY) VALUE('Thursday'))) 
35 1600- ELSE CMD(IF COND(&DAYOFWK *EQ 6) THEN(CHGV 
36 1700 VAR(&WEEKDAY) VALUE('Friday'))) 
37 1800- ELSE CMD(IF COND(&DAYOFWK *EQ 7) THEN(CHGV 
38 1900 VAR(&WEEKDAY) VALUE('Saturday'))) 
More... 
Debug... 
F3=End program F6=Add/Clear breakpoint F10=step Fll=Display variable 
F1l2=Resume F17=Watch variable F18=Work with watch F24=More keys 


i yw 


Figure 21. Display a Module View 


After you select the module object that you want to view, press Enter. The selected 
module object is shown in the Display Module Source display. 


An alternate method of changing a module object is to use the DISPLAY debug 
command. On the debug command line, type: 


DISPLAY MODULE module-name 


The module object module-name will now be shown. The module object must exist 
in a program or service program object that has been added to the debug session. 


Changing the View of a Module Object 
Several views of an ILE CL module object are available depending on the values 
you specify when you create an ILE CL module object. These views are: 


¢ Root source view 
* Listing view 


¢« Statement view 


You can change the view of the module object that is shown on the Display 
Module Source display through the Select View display. The Select View display 


can be accessed from the Display Module Source display by pressing F15 (Select 
View). The Select View display is shown in TaTeaIeree | The current 
view is listed at the top of the window, and the other views that are available are 
shown below. Each module object in a program object can have a different set of 
views available, depending on the debug options used to create it. 


To select a view, type 1 (Select) next to the view you want to show. 
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Display Module Source 
Select View 
Current View... : CL Root Source 


Type option, press Enter. 


1=Select 
Opt View 
CL Root Source 
1 CL Listing View 
Bottom 
F12=Cancel 
More 
Debug... 


F3=End Program F6=Add/Clear breakpoint F10=Step 11=Display variable 
F1l2=Resume F17=Watch variable F18=Work with watch F24=More keys 


Figure 22. Changing a View of a Module Object 


After you select the view of the module object that you want to show, press Enter 
and the selected view of the module object is shown in the Display Module Source 
display. 


Setting and Removing Breakpoints 

You can use breakpoints to halt a program object at a specific point when it is 
running. An unconditional breakpoint stops the program object at a specific 
statement. A conditional breakpoint stops the program object when a specific 
condition at a specific statement is met. 


When the program object stops, the Display Module Source display is shown. The 
appropriate module object is shown with the source positioned at the line where 
the breakpoint occurred. This line is highlighted. At this point, you can evaluate 
variables, set more breakpoints, and run any of the debug commands. 


You should know the following characteristics about breakpoints before using 
them: 


* When a breakpoint is bypassed, for example with the GOTO statement, that 
breakpoint isn’t processed. 


* When a breakpoint is set on a statement, the breakpoint occurs before that 
statement is processed. 


* When a statement with a conditional breakpoint is reached, the conditional 
expression associated with the breakpoint is evaluated before the statement is 
processed. 


* Breakpoint functions are specified through debug commands. 
These functions include: 
— Adding breakpoints to program objects 
— Removing breakpoints from program objects 
— Displaying breakpoint information 
— Resuming the running of a program object after a breakpoint has been 
reached. 
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Setting and Removing Unconditional Breakpoints 
You can set or remove an unconditional breakpoint by using: 


* F6 (Add/Clear breakpoint) from the Display Module Source display 

* F13 (Work with Module Breakpoints) from the Display Module Source display 
* The BREAK debug command to set a breakpoint 

* The CLEAR debug command to remove a breakpoint 


The simplest way to set and remove an unconditional breakpoint is to use F6 
(Add/Clear breakpoint) from the Display Module Source display. To set an 
unconditional breakpoint using F6, place your cursor on the line to which you 
want to add the breakpoint and press F6. An unconditional breakpoint is then set 
on the line. To remove an unconditional breakpoint, place your cursor on the line 
from which you want to remove the breakpoint and press F6. The breakpoint is 
then removed from the line. 


Repeat the previous steps for each unconditional breakpoint you want to set. 


Note: If the line on which you want to set a breakpoint is not a runnable 
statement, the breakpoint is set at the next runnable statement. 


After the breakpoints are set, press F3 (Exit) to leave the Display Module Source 
display. You can also use F21 (Command Line) from the Display Module Source 
display to call the program from a command line. 


Call the program object. When a breakpoint is reached, the program stops and the 
Display Module Source display is shown again. At this point, you can evaluate 
variables, set more breakpoints, and run any of the debug commands. 


An alternate method of setting and removing unconditional breakpoints is to use 
the BREAK and CLEAR debug commands. 


To set an unconditional breakpoint by using the BREAK debug command, type: 
BREAK 1ine-number 


on the debug command line. Line-number is the line number in the currently 
displayed view of the module object on which you want to set a breakpoint. 


To remove an unconditional breakpoint by using the CLEAR debug command, 


type: 


CLEAR 1ine-number 


on the debug command line. Line-number is the line number in the currently 
displayed view of the module object from which you want to remove a breakpoint. 


If using the statement view, there is no line numbers displayed. To set 
unconditional breakpoints in the statement view, type: 


BREAK procedure-name/statement-number 
on the debug command line. Procedure-name is the name of your CL module. 


Statement-number(from the compiler listing) is the statement number where you 
wanted. to stop. 
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Setting and Removing Conditional Breakpoints 
You can set or remove a conditional breakpoint by using: 


* The Work with Breakpoints display 
* The BREAK debug command to set a breakpoint 
* The CLEAR debug command to remove a breakpoint 


Using the Work with Breakpoints Display: 


Note: The relational operators supported for conditional breakpoints are <, >, =, 
<=, >=, and <> (not equal). 


One way you can set or remove conditional breakpoints is through the Work with 
Module Breakpoints display. The Work with Module Breakpoints display can be 
accessed from the Display Module Source display by pressing F13 (Work with 
Module Breakpoints). The Work with Module Breakpoints display is shown in 

To set a conditional breakpoint, type the following: 


¢ 1 (Add) in the Opt field, 

* the debugger line number where you want to set the breakpoint in the Line field, 
* a conditional expression in the Condition field, 

and press Enter. For example, to set a conditional breakpoint at debugger line 35, 
as shown in Figure 23, type the following: 

¢ 1 (Add) in the Opt field, 

¢ 35 in the Line field, 

* type &I=21 in the Condition field, 


and press Enter. 
To remove a conditional breakpoint, type 4 (Clear) in the Opt field next to the 


breakpoint you want to remove, and press Enter. You can also remove 
unconditional breakpoints in this manner. 


a an 
Work with Module Breakpoints 
System: SYSTEMO1 


Program ... :  MYPGM Library 4. 3 (MYLIB 
Moduiliesc. oaa MYMOD Type. 4s 2 .-  EXPGM 


Type options, press Enter. 
l=Add = 4=Clear 


Opt Line Condition 
1 35 &l=21 


\ - 


Figure 23. Setting a Conditional Breakpoint 


Repeat the previous steps for each conditional breakpoint you want to set or 
remove. 


Note: If the line on which you want to set a breakpoint is not a runnable 
statement, the breakpoint is set at the next runnable statement. 


After you specify all breakpoints that you want to set or remove, press F3 (Exit) to 
return to the Display Module Source display. 


358 OS/400 CL Programming V5R2 


Then press F3 (Exit) to leave the Display Module Source display. You can also use 
F21 (Command Line) from the Display Module Source display to call the program 
object from a command line. 


Call the program object. When a statement with a conditional breakpoint is 
reached, the conditional expression associated with the breakpoint is evaluated 
before the statement is run. If the result is false, the program object continues to 
run. If the result is true, the program object stops, and the Display Module Source 
display is shown. At this point, you can evaluate variables, set more breakpoints, 
and run any of the debug commands. 


Using the BREAK and CLEAR Debug Commands: An alternate method of 
setting and removing conditional breakpoints is to use the BREAK and CLEAR 
debug commands. 


To set a conditional breakpoint by using the BREAK debug command, type: 
BREAK line-number WHEN expression 


on the debug command line. Line-number is the line number in the currently 
displayed view of the module object on which you want to set a breakpoint. 
expression is the conditional expression that is evaluated when the breakpoint is 
encountered. The relational operators supported for conditional breakpoints are <, 
>, =, <=, >=, and <> (not equal). 


In non-numeric conditional breakpoint expressions, the shorter expression is 
implicitly padded with blanks before the comparison is made. This implicit 
padding occurs before any National Language Sort Sequence (NLSS) translation. 
for more information on NLSS. 


To remove a conditional breakpoint by using the CLEAR debug command, type: 
CLEAR 1ine-number 


on the debug command line. Line-number is number in the currently displayed 
view of the module object from which you want to remove a breakpoint. 


In the statement view, no line numbers are displayed. To set conditional 
breakpoints in the statement view, type: 


BREAK procedure-name/statement-name WHEN expression 


on the debug command line. Procedure-name is the name of your CL module. 
Statement-number(from the compiler listing) is the statement number where you 
want to stop. 


National Language Sort Sequence (NLSS): Non-numeric conditional breakpoint 
expressions are divided into the following two types: 


¢ Char- 8: each character contains 8 bits 
* Char-16: each character contains 16 bits (DBCS) 


NLSS applies only to non-numeric conditional breakpoint expressions of type 
Char-8. See fable Ian nage 260 for the possible combinations of non-numeric 
conditional breakpoint expressions. 

The sort sequence table used by the source debugger for expressions of type 


Char-8 is the sort sequence table specified for the SRTSEQ parameter on the 
CRTCLMOD or CRTBNDCL commands. 
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If the resolved sort sequence table is *HEX, no sort sequence table is used. 
Therefore, the source debugger uses the hexadecimal values of the characters to 
determine the sort sequence. Otherwise, the specified sort sequence table is used to 
assign weights to each byte before the comparison is made. Bytes between, and 
including, shift-out/shift-in characters are not assigned weights. 


Note: The name of the sort sequence table is saved during compilation. At debug 
time, the source debugger uses the name saved from the compilation to 
access the sort sequence table. If the sort sequence table specified at 
compilation time resolves to something other than *HEX or *JOBRUN, it is 
important the sort sequence table does not get altered before debugging is 
started. If the table cannot be accessed because it is damaged or deleted, the 
source debugger uses the *HEX sort sequence table. 


Table 10. Non-numeric Conditional Breakpoint Expressions 


Type Possibilities 


Char-8 ¢ Character variable compared to character variable 


* Character variable compared to character literal ! 
* Character variable compared to hex literal 7 

* Character literal ! compared to character variable 
* Character literal ! compared to character literal 2 
* Character literal ' compared to hex literal * 

* Hex literal 7 compared to character variable ' 

* Hex literal 7 compared to character literal ! 

* Hex literal 7 compared to hex literal * 


Char 16 * DBCS character variable compared to DBCS character 
variable 

¢ DBCS character variable compared to graphic literal 2 
* DBCS character variable compared to hex literal . 

* Graphic literal os compared to DBCS character variable 
* Graphic literal * compared to Graphic literal ° 

* Graphic literal * compared to hex literal * 

* Hex literal * compared to DBCS character variable 

* Hex literal > compared to Graphic literal ° 


Character literal is of the form ‘abc’. 
Hexadecimal literal is of the form X‘hex digits’. 


Graphic literal is of the form G’<so>DBCS data<si>’. Shift-out is represented as 
<so> and shift-in is represented as <si>. 


Conditional Breakpoint Examples: 


CL declarations: DCL  VAR(&CHAR1) TYPE(*CHAR) LEN(1) 
DCL  VAR(&CHAR2) TYPE(*CHAR) LEN(2) 
DCL VAR(&DEC1) TYPE(*DEC) LEN(3 1) 
DCL -VAR(&DEC2) TYPE(*DEC) LEN(4 1) 


Debug command: BREAK 31 WHEN &DEC1 = 48.1 
Debug command: BREAK 31 WHEN &DEC2 > &DEC1 
Debug command: BREAK 31 WHEN &CHAR2 <> 'A' 
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Comment: 'A' is implicitly padded to 
the right with one blank character before 
the comparison is made. 


Debug command: BREAK 31 WHEN %SUBSTR(&CHAR2 2 1) <= X'F1' 
Debug command: BREAK 31 WHEN %SUBSTR(&CHAR2 1 1) >= &CHARI 
Debug command: BREAK 31 WHEN %SUBSTR(&CHAR2 1 1) < %SUBSTR(&CHAR2 2 1) 


The %SUBSTR built-in function allows you to substring a character string variable. 
The first argument must be a string identifier, the second argument is the starting 
position, and the third argument is the number of single byte or double byte 
characters. Arguments are delimited by one or more spaces. 


Removing All Breakpoints 

You can remove all breakpoints, conditional and unconditional, from a program 
object that has a module object shown on the Display Module Source display by 
using the CLEAR PGM debug command. To use the debug command, type: 


CLEAR PGM 


on the debug command line. The breakpoints are removed from all of the modules 
bound to the program or service program. 


Stepping through the Program Object 


After a breakpoint is encountered, you can run a specified number of statements of 
a program object, then stop the program again and return to the Display Module 
Source display. The program object begins running on the next statement of the 
module object in which the program stopped. Typically, a breakpoint is used to 
stop the program object. 


You can step through a program object by using: 
* F10 (Step) or F22 (Step into) on the Display Module Source display 
* The STEP debug command 


Using F10 or F22 on the Display Source Display 

The simplest way to step through a program object one statement at a time is to 
use F10 (Step) or F22 (Step into) on the Display Module Source display. When you 
press F10 (Step) or F22 (Step into), then next statement of the module object shown 
in the Display Module Source display is run, and the program object is stopped 
again. 


Note: You cannot specify the number of statements to step through when you use 
F10 (Step) or F22 (Step into). Pressing F10 (Step) or F22 (Step into) performs 
a single step. 


Another way to step through a program object is to use the STEP debug command. 
The STEP debug command allows you to run more than one statement in a single 
step. 


Using the STEP Debug Command 
The default number of statements to run, using the STEP debug command, is one. 
To step through a program object using the STEP debug command, type: 


STEP number-of-statements 
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on the debug command line. Number-of-statementsis the number of statements of 
the program object that you want to run in the next step before the program object 
is halted again. For example, if you type 


STEP 5 


on the debug command line, the next five statements of your program object are 
run, then the program object is stopped again and the Display Module Source 
display is shown. 


Step Over and Step Into 
When a CALL statement to another program object is encountered in a debug 
session, you can do either of the following: 


* Step over the called program object, or 
* Step into the called program object. 


If you choose to step over the called program object, then the CALL statement and 
the called program object are run as a single step. The called program object is run 
to completion before the calling program object is stopped at the next step. Step 
over is the default step mode. 


If you choose to step into the called program object, then each statement in the 
called program object is run as a single step. If the next step at which the running 
program object is to stop falls within the called program object, the called program 
object is halted at this point. The called program object is then shown in the 
Display Module Source display if the called program object is compiled with 
debug data and you have the correct authority to debug it. 


Stepping over Program Objects 
You can step over program objects by using: 
* F10 (Step) on the Display Module Source display 
* The STEP OVER debug command 


Using F10(Step) 

You can use F10 (Step) on the Display Module Source display to step over a called 
program object in a debug session. If the next statement to be run is a CALL 
statement to another program object, then pressing F10 (Step) will cause the called 
program object to run to completion before the calling program object is stopped 
again. 


Using the Step Over Debug Command 
Alternatively, you can use the STEP OVER debug command to step over a called 
program object in a debug session. To use the STEP OVER debug command, type: 


STEP number-of-statements OVER 


on the debug command line. Number-of-statements is the number of statements of 
the program object that you want to run in the next step before the program object 
is halted again. If one of the statements that are run contains a CALL statement to 
another program object, the ILE source debugger steps over the called program 
object. 


Stepping into Program Objects 
You can step into program objects by using: 
* F22 (Step into) on the Display Module Source display 
* The STEP INTO debug command 
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Using F22(Step Into) 

You can use F22 (Step into) on the Display Module Source display to step into a 
called program object in a debug session. If the next statement to be run is a CALL 
statement to another program object, pressing F22 (Step into) causes the first 
statement in the called program object to be run. The called program object is then 
shown in the Display Module Source display. 


Note: The called program object must have debug data associated with it in order 
for it to be shown in the Display Module Source display. 


Using the Step Into Debug Command 
Alternatively, you can use the STEP INTO debug command to step into a called 
program object in a debug session. To use the STEP INTO debug command, type: 


STEP number-of-statements INTO 


on the debug command line. Number-of-statements is the number of statements of 
the program object that you want to run in the next step before the program object 
is halted again. If one of the statements that are run contains a CALL statement to 
another program object, the debugger steps into the called program object. Each 
statement in the called program object is counted in the step. If the step ends in 
the called program object then the called program object is shown in the Display 
Module Source display. For example, if you type 


STEP 5 INTO 


on the debug command line, the next five statements of the program object are 
run. If the third statement is a CALL statement to another program object, then 
two statements of the calling program object are run and the first three statements 
of the called program object are run. 


Displaying Variables 
You can display the value of variables by using: 
* F11 (Display variable) on the Display Module Source display 
* The EVAL debug command 


The scope of the variables used in the EVAL command is defined by using the 
QUAL command. However, you do not need to specifically define the scope of the 
variables contained in a CL module because they are all of global scope. 


Using F11(Display Variable) 

To display a variable using F11 (Display variable), place your cursor on the 
variable that you want to display and press F11. The current value of the variable 
is shown on the message line at the bottom of the Display Module Source display. 
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Display Module Source 

Program: DSPWKDAY Library: MYLIB Module: = DSPWKDAY 

4 DCL VAR(&MSGTEXT) TYPE(*CHAR) LEN(20) 

5 CALL PGM(WEEKDAY2) PARM(&DAYOFWK) 

6 RE COND(&DAYOFWK *EQ 1) THEN(CHGVAR + 

7 VAR(&WEEKDAY) VALUE('Sunday')) 

8 ELSE CMD(IF COND(&DAYOFWK *EQ 2) THEN(CHGVAR + 

9 VAR(&WEEKDAY) VALUE('Monday'))) 

10 ELSE CMD(IF COND(&DAYOFWK *EQ 3) THEN(CHGVAR + 

11 VAR(&WEEKDAY) VALUE('Tuesday'))) 

12 ELSE CMD(IF COND(&DAYOFWK *EQ 4) THEN(CHGVAR + 

13 VAR(&WEEKDAY) VALUE('Wednesday'))) 

14 ELSE CMD(IF COND(&DAYOFWK *EQ 5) THEN(CHGVAR + 

15 VAR(&WEEKDAY) VALUE('Thursday'))) 

16 ELSE CMD(IF COND(&DAYOFWK *EQ 6) THEN(CHGVAR + 

17 VAR(&WEEKDAY) VALUE('Friday'))) 

18 ELSE CMD(IF COND(&DAYOFWK *EQ 7) THEN(CHGVAR + 

More... 

Debug... 
F3=End program F6=Add/Clear breakpoint 10=Step 11l=Display variable 
F12=Resume F1l7=Watch Variable F18=Work with watch F24=More keys 
&DAYOFWK = 3. 


Figure 24. Displaying a Variable using F11 (Display variable). Using the EVAL Debug 
Command 


You can also use the EVAL debug command to determine the value of a variable. 
To display the value of a variable using the EVAL debug command, type: 


EVAL variable-name 


on the debug command line. Variable-name is the name of the variable that you 
want to display. The value of the variable is shown on the message line if the 
EVAL debug command is entered from the Display Module Source display and the 
value can be shown on a single line. If the value cannot be shown on a single line, 
it is shown on the Evaluate Expression display. 


For example, to display the value of the variable 6DAYOFWK,; on line 7 of the 
module object shown in Figure 24) type: 


EVAL &DAYOFWK 


The message line of the Display Module Source display shows &DAYOFWK = 3. as in 


Display logical variable example 
CL declarations: DCL VAR(&LGL1) TYPE(*LGL) VALUE('1') 


Debug command: EVAL &LGL1 


Result: &LGL1 = '1' 


Display character variable examples 
CL declarations: DCL VAR(&CHAR1) TYPE(*CHAR) LEN(10) VALUE('EXAMPLE') 


Debug command: EVAL &CHAR1 


Result: &CHAR1 = 'EXAMPLE ' 
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Debug command: EVAL %SUBSTR(&CHARI 5 3) 


Result: %SUBSTR(&CHARI 5 3) = 'PLE' 
Debug command: EVAL %SUBSTR(&CHARI 7 4) 
Result: %SUBSTR(&CHAR1 7 4) = 'E : 


The %SUBSTR built-in function allows you to substring a character string variable. 
The first argument must be a string identifier, the second argument is the starting 
position, and the third argument is the number of single byte or double byte 
characters. Arguments are delimited by one or more spaces. 


Display decimal variable example 
CL declarations: DCL - VAR(&DEC1) TYPE(*DEC) LEN(4 1) VALUE(73.1) 


CL declarations: DCL  VAR(&DEC2) TYPE(*DEC) LEN(3 1) VALUE(12.5) 


Debug command: EVAL &DEC1 
Result: &DEC1 = 073.1 
Debug command: EVAL &DEC2 
Result: &DEC2 = 12.5 


Displaying Variables as Hexadecimal Values 

You can use the EVAL debug command to display the value of variables in 
hexadecimal format. To display a variable in hexadecimal format, on the debug 
command line, type: 


EVAL variable-name: x number-of-bytes 


Variable-name is the name of the variable that you want to display in hexadecimal 
format. 'x' specifies that the variable is to be displayed in hexadecimal format and 
number-of-bytes indicates the number of bytes displayed. If no length is specified 
after the 'x', the size of the variable is used as the length. A minimum of 16 bytes is 
always displayed. If the length of the variable is less than 16 bytes, then the 
remaining space Is FILLED WITH ZEROES until the 16 byte boundary is reached. 


CL declaration: DCL  VAR(&CHARL) TYPE(*CHAR) LEN(10) VALUE('ABC') 
DCL VAR(&CHAR2) TYPE(*CHAR) LEN(10) VALUE('DEF') 


Debug command: EVAL &CHAR1:X 32 
Result: 


00000 C1C2C340 40404040 4040C4C5 C6404040 ABC DEF 
00010 40404040 00000000 00000000 Q0000000 _—_................ 


Changing the Value of Variables 


You can change the value of variables by using the EVAL command with the 
assignment operator (=). 


The scope of the variables used in the EVAL command is defined by using the 
QUAL command. However, you do not need to specifically define the scope of the 


variables contained in a CL module because they are all of global scope. 


You can use the EVAL debug command to assign numeric, character, and 
hexadecimal data to variables provided they match the definition of the variable. 
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To change the value of the variable, type: 
EVAL variable-name = value 


on the debug command line. Variable-name is the name of the variable that you 
want to change and value is an identifier or literal value that you want to assign to 
variable-name. For example, 


EVAL &COUNTER = 3.0 


changes the value of SCOUNTER; to 3.0 and shows 
&COUNTER = 3.0 = 3.0 


on the message line of the Display Module Source display. The result is preceded 
by the variable-name and value you are changing. 


When you assign values to a character variable, the following rules apply: 


* If the length of the source expression is less than the length of the target 
expression, the data is left justified in the target expression and the remaining 
positions are filled with blanks. 


* If the length of the source expression is greater than the length of the target 
expression, the data is left justified in the target expression and truncated to the 
length of the target expression. 


Note: DBCS variables can be assigned any of the following: 
¢ Another DBCS variable 
* A graphic literal of the form G’<so>DBCS data<si>’ 
* A hexadecimal literal of the form X’hex digits’ 


Change logical variable examples 


CL declarations: DCL VAR(&LGL1) TYPE(*LGL) VALUE('1') 
DCL VAR(&LGL2) TYPE(*LGL) 


Debug command: EVAL &LGL1 
Result: &L@Ll = '1' 
Debug command: EVAL &LGL1 = X'FO' 
Result: &LGLl = X'FQ' = 'Q' 
Debug command: EVAL &LGL2 = &LGLl 
Result: &LGL2 = &LGL1 = '0' 


Change character variable examples 


CL declarations: DCL  VAR(&CHAR1) TYPE(*CHAR) LEN(1) VALUE('A') 
DCL VAR(&CHAR2) TYPE(*CHAR) LEN(10) 


Debug command: EVAL &CHAR1 = 'B' 
Result: &CHARI = 'B' = 'B' 
Debug command: EVAL &CHAR1 = X'FOFIF2F3' 
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Result: &CHAR1 = 'FOFI1F2F3' = '0! 


Debug command: EVAL &CHAR2 = 'ABC' 

Result: &CHAR2 = 'ABC' = 'ABC : 

Debug command: EVAL %SUBSTR(CHAR2 1 2) = %SUBSTR(&CHAR2 3 1) 
Result: %SUBSTR(CHAR2 1 2) = %SUBSTR(&CHAR2 3 1) = 'C '' 
Comment : Variable &CHAR contains 'C C ' 


The %SUBSTR built-in function allows you to substring a character string variable. 
The first argument must be a string identifier, the second argument is the starting 
position, and the third argument is the number of single byte or double byte 
characters. Arguments are delimited by one or more spaces. 


Change decimal variable examples 


CL declarations: DCL —-VAR(&DEC1) TYPE(*DEC) LEN(3 1) VALUE(73.1) 
DCL -VAR(&DEC2) TYPE(*DEC) LEN(2 1) VALUE(3.1) 


Debug command: EVAL &DEC1 = 12.3 
Result: &DEC1 = 12.3 = 12.3 
Debug command: EVAL &DEC1 = &DEC2 
Result: &DEC1 = &DEC2 = 03.1 


Attributes of a Variable Examples 
The Attribute (ATTR) debug command permits you to display the attributes of a 


variable. The attributes are the size (in bytes) and type of the variable as recorded 
in the debug symbol table on 


The following is an example using the ATTR debug command. 
CL declaration: DCL VAR(&CHAR2) TYPE(*CHAR) LEN(10) 


Debug command: ATTR &CHAR2 


Result: TYPE = FIXED LENGTH STRING, LENGTH = 10 BYTES 


CL declaration: DCL VAR(&DEC) TYPE(*DEC) LEN(3 1) 
Debug command: ATTR &DEC 


Result: TYPE = PACKED(3,1), LENGTH = 2 BYTES 


Equating a Name with a Variable, Expression, or Command 


You can use the EQUATE debug command to equate a name with a variable, 
expression or debug command for shorthand use. You can then use that name 
alone or within another expression. If you use it within another expression, the 
value of the name is determined before the expression is evaluated. These names 
stay active until a debug session ends or a name is removed. 


To equate a name with a variable, expression or debug command, type: 
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EQUATE shorthand-name definition 


on the debug command line. shorthand-name is the name that you want to equate 
with a variable, expression, or debug command, and definition is the variable, 
expression, or debug command that you are equating with the name. 


For example, to define a shorthand name called DC that displays the contents of a 
variable called COUNTER, type: 


EQUATE DC EVAL &COUNTER 


on the debug command line. Now, each time DC is typed on the debug command 
line, the command EVAL &COUNTER is performed. 


The maximum number of characters that can be typed in an EQUATE command is 
144. If a definition is not supplied and a previous EQUATE command defined the 

name, the previous definition is removed. If the name was not previously defined, 
an error message is shown. 


To see the names that have been defined with the EQUATE debug command for a 
debug session, type: 
DISPLAY EQUATE 


on the debug command line. A list of the active names is shown on the Evaluate 
Expression display. 


Source Debug National Language Support for ILE CL 
The following conditions exist when you are working with source debug National 
Language Support for ILE CL. 


* When a view is displayed on the Display Module Source display, the source 
debugger converts all data to the Coded Character Set Identifier (CCSID) of the 
debug job. 


* When assigning literals to variables, the source debugger does not perform 
CCSID conversion on quoted literals (for example ‘abc’). Also, quoted literals are 
case sensitive. 


Working with *SOURCE View 
The following condition is true only when you are working with the CL Root 
Source View: 


¢ If the source file CCSID is different from the module CCSID, the source 
debugger may not recognize a CL identifier containing variant characters (#, @, 


The CCSID of the module can be found using the Display Module (DSPMOD) CL 
command. If you need to work with CL Root Source View and the source file 
CCSID is different from the module CCSID, you can take one of the following 
actions: 


* Ensure the CCSID of CL source is the same as the CCSID of the compile-time 
job. 

* Change the CCSID of the compile-time job to 65 535 and compile. 

* Use the CL Listing View if the previous two options are not possible. 


See the fe Conceal book, Chapter 10, “Debugging Considerations” for more 


information on national language Restrictions for Debugging. 
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Using COPY, SAVE, RESTORE, CRTDUPOByJ, and CHKOBJITG 
while Debugging 

Breakpoints or steps may be temporarily removed from a program while 
debugging when you use certain control language (CL) commands to specify your 
library or program. Breakpoints and steps are restored when the CL command 
completes running. A CPD190A message will be in the job log when the 
breakpoints or steps are removed; another CPD190A message will be in the job log 
when the breakpoints or steps are restored. 


The following are the CL commands which can cause the breakpoint or step to be 
temporarily removed: 


CHKOBJITG CPY CPROBJ RSTLIB SAVLIB 
CPYLIB CRTDUPOBJ RSTOBJ SAVOBJ 
SAVSYS 

SAVCHGOBJ] 


Note: When the CL commands are operating on the program, you will receive 
error message CPF7102 when you issue the BREAK or STEP command. 


Debugging OPM Programs 


Testing functions are designed to help you write and maintain your applications. It 
lets you run your programs in a special testing environment while closely 
observing and controlling the processing of these programs in the testing 
environment. You can interact with your programs using the testing functions 
described in this chapter. These functions are available through a set of commands 
that can be used interactively or in a batch job. The functions allow you to: 


* Trace a program’s processing sequence and show the statements processed and 
the values of program variables at each point in the sequence. 


* Stop at any statement in a program (called a breakpoint) and receive control to 
perform a function such as displaying or changing a variable value or calling 
another user-defined program. 


No special commands specifically for testing are contained in the program being 
tested. The same program being tested can be run normally without changes. All 
test commands are specified within the job the program is in, not as a permanent 
part of the program being tested. With the testing commands, you interact with the 
programs symbolically in the same terms as the high-level language (HLL) 
program was written in. You refer to variables by their names and statements by 
their numbers. (These are the numbers used in the program’s source list.) In 
addition, the test functions are only applicable to the job they are set up in. The 
same program can be used at the same time in another job without being affected 
by the testing functions set up. 


Debug Mode 


To begin testing, your program must be put in debug mode. Debug mode is a 
special environment in which the testing functions can be used in addition to the 
normal system functions. Testing functions cannot be used outside debug mode. To 
start debug mode, you must use the Start Debug (STRDBG) command. In addition 
to placing your program in debug mode, the STRDBG command lets you specify 
certain testing information such as the programs that are being debugged. Your 
program remains in debug mode until an End Debug (ENDDBG) or Remove 
Program (RMVPGM) command is encountered or your current routing step ends. 
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Note: If the System Debug Manager function in iSeries Navigator has been used to 
select Debug in order to check the system, then issuing the Start Debug (STRDBG) 
command will cause the graphical interface to be presented. In this case, whenever 
one of the users specified in the user list issues the STRDBG command, they will 
see the iSeries Navigator System Debug Manager rather than the Command Entry 
display. If the ENDDBG command is entered and Debug in the System Debug 
Manager is not currently selected, then issuing the STRDBG command will again 
invoke the system debugger using the Command Entry display. 


The following STRDBG command places the job in debug mode and adds program 
CUS310 as the program to be debugged. 


STRDBG PGM(CUS310) 


The option exists to use the ILE source debugger to debug OPM programs. To 
create OPM programs that contain source debug data, specify the 
OPTION(*SRCDBG) parameter on the Create CL Program (CRTCLPGM) command. 
The source debug data is actually part of the program object. 


To add OPM programs that get created containing source debug data to the ILE 
source debugger, use the Program (PGM) and OPM Source Level Debug 
(OPMSRC) parameters on the STRDBG command. To start a debug session with an 
OPM program created with source debug data, type: 


STRDBG PGM(*LIBL/MYOPMPGM) OPMSRC(*YES) DSPMODSRC(*YES) 


For more information on ILE source debugging , see “{D 


Adding Programs to Debug Mode 

Any program can be run in debug mode, but before you can debug it, you must 
put it in debug mode. You can place a program in debug mode by specifying it in 
the PGM parameter on the STRDBG command or by adding it to the debugging 
session with an Add Program (ADDPGM) command. You can specify as many as 
twenty (20) programs to be debugged simultaneously in a job. You must have 
*“CHANGE authority to add a program to debug mode. 


If you specified twenty (20) programs for debug mode (using either the STRDBG 
or ADDPGM command or both commands) and you want to add more programs 
to the debug job, you must remove some of the previously specified programs. Use 
the Remove Program (RMVPGM) command. When debug mode ends, all 
programs are automatically removed from debug mode. 


When you start debug mode, you can specify that a program be a default program. 
By specifying a default program, you can use any debug command that has the 
PGM parameter without having to specify a program name each time a command 
is used. This is helpful if you are only debugging one program. For example, in the 
Add Breakpoint (ADDBKP) command, you would not specify a program name on 
the PGM parameter because the default program is assumed to be the program the 
breakpoint is being added to. The default program name must be specified in the 
list of programs to be debugged (PGM parameter). If more than one program is 
listed to be debugged, you can specify the default program on the DFTPGM 
parameter. If you do not, the first program in the list on the PGM parameter on the 
STRDBG command is assumed to be the default program. 


The default program can be changed any time during testing by using either the 
Change Debug (CHGDBG) or the ADDPGM command. 
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Note: If a program that is in debug mode is deleted, re-created, or saved with 
storage freed, references made to that program (except a RMVPGM 
command) may result in a function check. You must either remove the 
program using a RMVPGM command or end debug mode using an 
ENDDBG command. If you want to change the program and then debug it, 
you must remove it from debug mode and after it is re-created, add it to 
debug mode (ADDPGM command). 


Preventing Updates to Database Files in Production Libraries 
You can use files in production libraries while you are in debug mode. To prevent 
database files in production libraries from being unintentionally changed, you can 
specify UPDPROD(*NO) or default to *NO on the STRDBG command. Then, only 
files in test libraries can be opened for updating or adding new records. If you 
want to open database files in production libraries for updating or adding new 
records or if you want to delete members from production physical files, you can 
specify UPDPROD(*YES). 


You can use this function with the library list. In the library list for your debug job, 
you can place a test library before a production library. You should have copies of 
the production files that might be updated by the program being debugged in the 
test library. Then, when the program runs, it uses the files in the test library. 
Therefore, production files cannot be unintentionally updated. 


The Call Stack 


You can use the Display Debug (DSPDBG) command to display the call stack, 

which indicates: 

* Which programs are currently being debugged 

* The instruction number of the calling instruction or the instruction number of 
each breakpoint at which program processing is stopped 

* The program recursion level 

* The names of the programs that are in debug mode but have not been called 


A call of a program is the allocation of automatic storage for the program and the 
transfer of machine processing to the program. A series of calls is placed in a call 
stack. When a program finishes processing or transfers control, it is removed from 
the call stack. For more information about the call stack, see 


A program may be called a number of times while the first call is still in the call 
stack. Each call of a program is a recursion level of the program. 


When a call is ended (the program returns or transfers control), automatic storage 
is returned to the system. 


Notes: 


1. CL programs can be recursive; that is, a CL program can call itself either 
directly or indirectly through a program it has called. 


2. Some high-level languages do not allow recursive program calls. Other 
languages allow not only programs to be recursive, but also procedures within 
a program to be recursive. (In this guide, the term recursion level refers to the 
number of times the program has been called in the call stack. A procedure’s 
recursion level is referred to explicitly as the procedure recursion level.) 


3. All CL commands and displays make use of only the program qualified name 
recursion level. 
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Program Activations 
An activation of a program is the allocation of static storage for the program. An 
activation is always ended when one of the following happens: 


* The current routing step ends. 
* The request that activated the program is canceled. 


* The Reclaim Resources (RCLRSC) command is run such that the last (or only) 
call of a program is ended. 


In addition, an activation can be destroyed by actions taken during a program call. 
These actions are dependent on the language (HLL or CL) in which the program is 
written. 


When a program is deactivated, static storage is returned to the system. The 
language (HLL or CL) in which the program is written determines when the 
program is normally deactivated. A CL program is always deactivated when the 
program ends. 


An RPG/400® program is deactivated when the last record indicator (LR) is set on 
before the program ends. If there is a return operation and LR is off, the program 
is not deactivated. 


Handling Unmonitored Messages 


Normally, if a program receives an unmonitored escape message, the system sends 
the function check message (CPF9999) to the program’s program message queue 
and the program stops processing. However, HLL program compilers may insert 
monitors for the function check message or for messages that may occur in the 
program. (An inquiry message is sent to the program messages display.) This 
allows you to end the program the way you want. In an interactive debug job, 
when a function check occurs, the system provides default handling and gives you 
control instead of stopping the program. The system displays the following on the 
unmonitored message display: 


* The message 


¢ The MI instruction number and HLL statement identifier, if available, to which 
the message was sent 


* The name and recursion level of the program to which the message was sent 


The following is an example of an unmonitored message breakpoint display: 
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r = 


Display Unmonitored Message Breakpoint 


Statement/Instruction. ...... : 440 /0077 
PROORalNineu cy ster est cries ee ha taremse coe NEES 
REcuRsiomelevellies were teu. creer en os 1 


Errors occurred on command. 


Press Enter to continue. 


F3=Exit program F10=Command Entry 
\ y 


You can try to isolate the source of the error by using the testing functions. 
However, the original request in error is still stopped at the point where the error 
occurred. To remove the request in error from the call stack, you must use the End 
Request (ENDRQS) command or press F3 when the unmonitored message 
breakpoint display is shown. You can let the usual function check processing 
continue by pressing the Enter key when the unmonitored message breakpoint 
display is shown. If you press F10 to call the command entry display, you must 
press F3 to return to the unmonitored message breakpoint display. 
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The following shows how a ENDRQS command works: 


Command 
Entry Display 


Cancel 


the Request 


to CALL PGMA 


CALL PGMA 


'___» PGMA 


(error occurs) 


Pressing Enter 
Continues 


Function Check ——*)_ Unmonitored 
Message 
F 
Breakpoint ; 
Display 
F10 Command 
Entry Display 


ENDRQS 


| 


RBAFN533-0 


Program calls are destroyed when a ENDRQS command is entered. (In the 
previous diagram, the program call of PGMA is destroyed.) 


Breakpoints 


A breakpoint is a place in a program at which the system stops program 
processing and gives control to you at a display station (interactive mode) or to a 
program specified on the BKPPGM parameter in the Add Breakpoint (ADDBKP) 
command (batch mode). 


Adding Breakpoints to Programs 

Use the ADDBKP command to add breakpoints to the program you want 
debugged. You can specify up to 10 statement identifiers on the one ADDBKP 
command. The program variables specified on an ADDBKP command apply only 
to the breakpoints specified on that command. Up to 10 variables can be specified 
in one ADDBKP command. 


You can also specify the name of the program to which the breakpoint is to be 
added. If you do not specify the name of the program that you want the 
breakpoint added to, the breakpoint is added to the default program specified on 
the STRDBG, CHGDBG, or ADDPGM command. 


For more information about breakpoint commands, see the CL section of the 
Programming category of the iSeries Information Center. 


To add a breakpoint to a program, specify a statement identifier, which can be: 
* A statement label 
* A statement number 


* A machine interface (MI) instruction number 
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When you add a breakpoint to a program, you can also specify program variables 
whose values or partial values you want to display when the breakpoint is 
reached. These variables can be shown in character or hexadecimal format. 


Program processing stops at a breakpoint before the instruction is processed. For an 
interactive job, the system displays what breakpoint the program has stopped at 
and, if requested, the values of the program variables. 


In high-level language programs, different statements and labels may be mapped 
to the same internal instruction. This happens when there are several inoperable 
statements (such as DO and ENDDO) following one another in a program. You can 
use the IRP list to determine which statements or labels are mapped to the same 
instruction. 


The result of different statements being mapped to the same instruction is that a 
breakpoint being added may redefine a previous breakpoint that was added for a 
different statement. When this occurs, a new breakpoint replaces the previously 
added breakpoint, that is, the previous breakpoint is removed and the new 
breakpoint is added. After this information is displayed, you can do any of the 
following: 


* End the most recent request by pressing F3. 
* Continue program processing by pressing Enter. 


* Go to the command entry display at the next request level by pressing F10. 
From this display, you can: 


— Enter any CL command that can be used in an interactive debug 
environment. You may display or change the values of variables in your 
program, add or remove programs from debug mode, or perform other debug 
commands. 


— Continue processing the program by entering the Resume Breakpoint 
(RSMBKP) command. 


— Return to the breakpoint display by pressing F3. 


— Return to the command entry display at the previous request level by 
entering the End Request (ENDRQS) command. 


For a batch job, a breakpoint program can be called when a breakpoint is reached. 
You must create this breakpoint program to handle the breakpoint information. 
The breakpoint information is passed to the breakpoint program. The breakpoint 
program is another program such as a CL program that can contain the same 
commands (requests for function) that you would have entered interactively for an 
interactive job. For example, the program can display and change variables or add 
and remove breakpoints. Any function valid in a batch job can be requested. When 
the breakpoint program completes processing, the program being debugged 
continues. 


A message is recorded in the job log for every breakpoint for the debug job. 
The following ADDBKP commands add breakpoints to the program CUS310. 


CUS310 is the default program, so it does not have to be specified. The value of 
the variable &ARBAL is shown when the second breakpoint is reached. 

ADDBKP STMT(900) 

ADDBKP STMT(2200) PGMVAR('&8ARBAL') 


Note: A CL variable must be entered with surrounding apostrophes. 
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The source for CUS310 looks like this: 


5728PW1 RO1MOO 880101 SEU SOURCE LISTING 
SOURCE FILE... .... QGPL/QCLSRC 
MEMBER: ie se) Se ws we a os CUS310 


SEQNBRe ee Pecic Us eteues (2 cise Fives 3 unstic nd Ae cove Re ne Daten O> aastece 0 aetewe (8 cues 


100 PGM  PARM(&NBRITEMS &ITEMPRC &PARBAL &PTOTBAL) 

200 DCL VAR(&PARBAL) TYPE(*DEC) LEN(15 5) /* INPUT AREA INV BALANCE */ 
300 DCL VAR(&PTOTBAL) TYPE(*DEC) LEN(15 5) /* INPUT TOTAL INV BALANCEx/ 
400 DCL VAR(&NBRITEMS) TYPE(*DEC) LEN(15 5) /* NUMBER OF ITEMS */ 
500 DCL VAR(&ITEMPRC) TYPE(*DEC) LEN(15 5) /* PRICE OF THE ITEM */ 
600 DCL VAR(&ARBAL) TYPE(*DEC) LEN(5 2) /* AREA INVENTORY BALANCE */ 
700 DCL VAR(&TOTBAL) TYPE(*DEC) LEN(5 2) /* TOTAL INVENTORY BALANCE*/ 
800 DCL VAR(&TOTITEM) TYPE(*DEC) LEN(5 2) /* TOTAL PRICE OF ITEMS x/ 
900 CHGVAR VAR(&ARBAL) VALUE (&PARBAL) 

1000 CHGVAR VAR(&TOTBAL) VALUE (&PTOTBAL) 

1100 IF COND(&NBRITEMS *EQ @) THEN(DO) 


1200 SNDPGMMSG MSG('The number of items is zero. This item + 
1300 should be ordered.') TOMSGQ(INVLIB/INVQUEUE) 
1400 GOTO CMDLBL (EXIT) 

1500  ENDDO 


1600 CHGVAR VAR(&TOTITEM) VALUE(&NBRITEMS * &ITEMPRC) 
1700 IF COND(&NBRITEMS *GT 50) THEN(DO) 


1800 SNDPGMMSG MSG('Too much inventory for this item.') + 
1900 TOMSGQ(INVLIB/ INVQUEUE) 
2000  ENDDO 


2100  CHGVAR VAR(&ARBAL) VALUE(&ARBAL + &TOTITEM) 
2200 IF COND(&ARBAL *GT 1000) THEN(DO) 


2300 SNDPGMMSG MSG('The area has too much money in + 
2400 inventory.') TOMSGQ(INVLIB/INVQUEUE) 
2500  ENDDO 

2600 CHGVAR VAR(&TOTBAL) VALUE(&TOTBAL + &TOTITEM) 
2700 ~=sEXIT: ENDPGM 


The following is displayed as a result of reaching the first breakpoint: 


GG 
Display Breakpoint 
Statement/Instruction.........: 900 /0009 
ROG IAM neers econ eens ceaeenrad tasares ease se CUSSTO 
Recurstonalhevell so cea (i ears: 1 ec veu eels eects 1 


Press Enter to continue. 


F3=Exit program F10=Command entry 
So 


The following is displayed as a result of reaching the second breakpoint: 
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ie = 


Display Breakpoint 


Statement/Instruction.........: 2200 /0022 

PrOGiaMi sa: cs meeees Pe ees es eee S CUSSTO 

RecuRsionislevell 2c cs, 38 secs ce fer tae) ee es 1 

Start. position: <3 3 a 442 SS wile we 1 

RONMAE cece cr yat wus oP en eee ak ee et *CHAR 

E@MORIS erescre fon ouces ve weete, cep) Cutest eae *DCL 

ViaisTiab il Ga var cee ce ursv esueccuasu sy ccp usr cute us dace cetcs &ARBAL 
VD OS Ore cmroa are srs: so renrourol smectic i cr ers PACKED 
EHO thir ccteewspercte ene simoucce euler a romesee a 52 
'610.00' 


Press Enter to continue. 


F3=Exit program F10=Command entry 
XY y 


The variable &ARBAL is shown. (Note that the value of &ARBAL will vary 
depending on the parameter values passed to the program.) You can press F10 to 
display the command entry display so that you could change the value of the 
variable &ARBAL to alter your program’s processing. You use the Change Program 
Variable (CHGPGMVAR) command to change the value of a variable. 


Conditional Breakpoints 

You may add a conditional breakpoint to a program that is being debugged. Use 
the Add Breakpoint (ADDBKP) command to specify the statement and condition. 
If the condition is met, the system stops the program processing at the specified 
statement. 


You may specify a skip value on the ADDBKP command. A skip value is a 
number that indicates how many times a statement should be processed before the 
system stops the program. For example, to stop a program at statement 1200 after 
the statement has been processed 100 times, enter the following command: 


ADDBKP STMT(1200) SKIP(100) 


If you specify multiple statements when the SKIP parameter is specified, each 
statement has a separate count. The following command causes your program to 
stop on statement 150 or 200, but only after the statement has processed 400 times: 


ADDBKP STMT(15@ 200) SKIP(400) 


If statement 150 has processed 400 times but statement 200 has processed only 300 
times, then the program does not stop on statement 200. 


If a statement has not processed as many times as was specified on the SKIP 
parameter, the Display Breakpoint (DSPBKP) command can be used to show how 
many times the statement was processed. To reset the SKIP count for a statement 
to zero, enter the breakpoint again for that statement. 


You can specify a more general breakpoint condition on the ADDBKP command. 
This expression uses a program variable, an operator, and another variable or 
constant as the operands. For example, to stop a program at statement 1500 when 
variable &X is greater than 1000, enter the following command: 
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ADDBKP STMT(1500) PGMVAR('&X') BKPCOND(*PGMVAR1 *GT 1000) 


The BKPCOND parameter requires three values: 


* In the example, the first value specifies the first variable specified on the 
PGMVAR parameter. (To specify the third variable, you would use *PGMVAR3.) 


* The second value must be an operator. For a list of all valid operators, see the 
CL section of the Programming category of the iSeries Information Center. 


* The third value may be a constant or another variable. A constant may be a 
number, character string, or bit string, and must be the same type as the 
program variable specified in the first value. 


The SKIP and BKPCOND parameters can be used together to specify a complex 
breakpoint condition. For example, to stop a program on statement 1000 after the 
statement has been processed 50 times and only when the character string &STR is 
TRUE, enter the following command: 


ADDBKP STMT(1000) PGMVAR('&STR') SKIP(50) 
BKPCOND(*PGMVAR1 *EQ 'TRUE ') 


Removing Breakpoints from Programs 

To remove breakpoints from a program, use the Remove Breakpoint (RMVBKP) 
command. To remove a breakpoint you must specify the statement number of the 
statement for which the breakpoint has been defined. 


Traces 


A trace is the process of recording the sequence in which the statements in a 
program are processed. A trace differs from a breakpoint in that you are not given 
control during the trace. The system records the traced statements that were 
processed. However, the trace information is not automatically displayed when the 
program completes processing. You must request the display of trace information 
using the Display Trace Data (DSPTRCDTA) command. The display shows the 
sequence in which the statements were processed and, if requested, the values of 
the variables specified on the Add Trace (ADDTRC) command. 


Adding Traces to Programs 

Adding a trace consists of specifying what statements are to be traced and, if you 
want, the names of program variables. Before a traced statement processes, the 
value of the variable is recorded. Also, you can specify that the values of the 
variables are to be recorded only if they have changed from the last time a traced 
statement was processed. These variables can be displayed in character format or 
hexadecimal format. 


To specify which statements are to be traced, you can specify: 


¢ The statement identifier at which the trace is to start and the statement identifier 
at which the trace is to stop 


* That all statements in the program are to be traced 
* A-single statement identifier of a statement to be traced 


On the STRDBG or CHGDBG command, you can specify how many statement 
traces can be recorded for a job and what action the system should take when the 
maximum is reached. When the maximum is reached, the system performs one of 
the following actions (depending on what you specify): 


* For an interactive job, either of the following can be done: 


— Stop the trace (*STOPTRC). Control is given to you (a breakpoint occurs), and 
you can remove some of the trace definitions (RMVTRC command), clear the 
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trace data (CLRTRCDTA command), or change the maximum (MAXTRC 
parameter on the CHGDBG command). 


— Continue the trace *WRAP). Previously recorded trace data is overlaid with 
trace data recorded after this point. 


* For a batch job, either of the following can be done: 


— Stop the trace (*STOPTRC). The trace definitions are removed and the 
program continues processing. 


— Continue the trace (*WRAP). Previously recorded trace data is overlaid with 
trace data recorded after this point. 


You can change the maximum and the default action any time during the debug 
job using the Change Debug (CHGDBG) command. However, the change does not 
affect traces that have already been recorded. 


You can only specify a total of five statement ranges for a single program at any 
one time, which is a total taken from all the Add Trace (ADDTRC) commands for 
the program. In addition, only 10 variables can be specified for each statement 
range. 


In high-level language programs, different statements and labels may be mapped 
to the same internal instruction. This happens when there are several inoperable 
statements (such as DO, END) following one another in a program. You can use 
the IRP list to determine which statements or labels are mapped to the same 
instruction. 


When you specify CL variables, you must enclose the & and the variable name in 
single apostrophes. For example: 


ADDTRC PGMVAR('&INQ1') 


When you specify a statement range, the source statement number for the stop 
statement is ordinarily larger than the number for the start statement. Tracing, 
however, is performed with machine interface (MI) instructions, and some 
compilers (notably RPG/400) generate programs in which the order of MI 
instructions is not the same as the order of the source statements. Therefore, in 
some cases, the MI number of the stop statement may not be larger than the MI 
number of the start statement, and you will receive message CPF1982. 


When you receive this message, you should do one of the following: 

* Trace all statements in the program. 

* Restrict a statement range to one specification. 

* Use MI instruction numbers gotten from_an intermediate representation of a 


program — list of the program. (See (Debugging a 
) 


The following Add Trace (ADDTRC) command adds a trace to the program 
CUS310. CUS310 is the default program, so it does not have to be specified. The 
value of the variable &TOTBAL is recorded only if its value changes between the 
times each traced statement is processed. 


ADDTRC STMT((900 2700)) PGMVAR('&TOTBAL') OUTVAR(*CHG) 


The following displays result from this trace and are displayed using the Display 
Trace Data (DSPTRCDTA) command. Note that column headers are not supplied 
for all displays. 
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Instruction Stepping 

You can step through the instructions of a program by using the STRDBG or 
CHGDBG commands and setting the MAXTRC parameter to 1 and the TRCFULL 
parameter to *STOPTRC. When you specify a trace range (ADDTRC command) 
and the program processes an instruction within that range, a breakpoint display 
with an error message appears. If you press Enter, another breakpoint display with 
the same error message appears for the next instruction processed in the trace 
range. When tracing is completed, the trace data contains a list of the instructions 
traced. You can display this data by entering the Display Trace Data (DSPTRCDTA) 
command. 


Using Breakpoints within Traces 

Breakpoints can be used within a trace range. At a breakpoint within a trace, you 
can display the trace data (DSPTRCDTA command) to determine if you need to 
take some action. The trace data is recorded before the breakpoint occurs. The trace 
information contains the value of any variables before the statement was processed. 


Removing Trace Information from the System 

On the DSPTRCDTA command, you can specify whether the trace information is 
removed from the system or left on the system after the information is displayed. 
If you leave the trace information on the system, any other traces are added to it. 
The information remains on the system (unless removed) until the debug job ends 
or the ENDDBG command is submitted. You can also use the Clear Trace Data 
(CLRTRCDTA) command to remove trace information from the system. 


Removing Traces from Programs 

The Remove Trace (RMVTRC) command removes all or some of the ranges 
specified in one or more Add Trace (ADDTRC) commands. Removing a trace range 
consists of specifying the statement identifiers used on the RMVTRC command, or 
specifying that all ranges be removed. 


You can use the STMT parameter on the RMVTRC command to specify: 


* All HLL statements and/or machine instructions in the specified program are 
not to be traced regardless of how the trace was defined by the ADDTRC 
command. 
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* The start and stop trace location of the HLL statements and/or system 
instructions to be removed. 


The RMVPGM and ENDDBG commands also remove traces, but they also remove 
the program from debug mode. 


Display Functions 


In debug mode, you can display testing information that lets you review how you 
have set up your debug job. You can display what programs are in debug mode 
and what breakpoints and traces have been defined for those programs. In 
addition, you can display the status of the programs in debug mode. 


You can use the following commands to display testing information: 


* Display Debug (DSPDBG), which displays the current call stack and the names 
of the programs that are in debug mode and indicates the following: 


— Which are stopped at a breakpoint 

— Which are currently called 

— The request level of those that are called 
— Debug options selected for the debug job 


* Display Breakpoint (DSPBKP), which displays the locations of breakpoints that 
are currently defined in a program. 


* Display Trace (DSPTRC), which displays the statements or statement ranges that 
are currently defined in a program. 


Displaying the Values of Variables 


When you are at a breakpoint, you can display the values of program variables. 
You can have this done automatically on the breakpoint display by specifying the 
variable names on the ADDBKP command, or you can enter the Display Program 
Variable (DSPPGMVAR) command at the breakpoint by pressing F10 to show the 
command entry display. Only 10 variables can be specified on one DSPPGMVAR 
command. For character and bit variables, you can tell the system to begin 
displaying the value of the variable starting at a certain position and for a specified 
length. Variables can be displayed in either character or hexadecimal format. 


Notes: 
1. If you specify an array variable, you can do one of the following: 


a. Specify the subscript values of the array element you want to display. The 
subscript values can either be integer values or the names of numeric 
variables in the program. 


b. Display the entire array by not entering any subscripts. 


c. Display a single-dimension cross-section of the array by specifying values 
for all subscripts except one, and an asterisk for that one subscript value. 

2. Variable names can be specified as simple or qualified names, but must be 
placed between apostrophes. A qualified name can be specified in either of two 
ways: 

a. Variable names alternating with the special separator words OF or IN, 
ordered from lowest to highest qualification level. A blank must separate 
the variable name and the special separator word. 

b. Variable names separated by periods, ordered from highest to lowest 
qualification level. 
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The following DSPPGMVAR command displays the variable ARBAL used in the 
program CUS310. CUS310 is the default program, so it does not have to be 
specified. The entire value is to be displayed in character format. 


DSPPGMVAR PGMVAR('&ARBAL') 


The resulting display looks like this: 
7 
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Some HLLs allow variables to be based on a user-specified pointer variable (HLL 
pointer). If you do not specify an explicit pointer for a based variable, the pointer 
specified in the HLL declaration (if any) is used. You must specify an explicit 
basing pointer if one was not specified in the HLL declaration for the based 
variable. The PGMVAR parameter allows you to specify up to five explicit basing 
pointers when referring to a based variable. When multiple basing pointers are 
specified, the first basing pointer specified is used to locate the second basing 
pointer, the second one is then used to locate the third, and so forth. The last 
pointer in the list of basing pointers is used to locate the primary variable. 


Changing the Values of Variables 


To change the value of a program variable, use the Change Program Variable 
(CHGPGMVAR), the Change HLL Pointer (CHGHLLPTR), or the Change Pointer 
(CHGPTR) command. Changing the value of a program variable consists of 
specifying the variable name and a value that is compatible with the data type of 
the variable. For example, if the variable is character type, you must enter a 
character value. 


When changing the value of variables, you should be aware of whether the 
variable is an automatic variable or a static variable. The difference between the 
two is in the storage for the variables. For automatic variables, the storage is 
associated with the call of the program. Every time a program is called, a new 
copy of the variable is placed in automatic storage. A change to an automatic 
variable remains in effect only for the program call the change was made in. 


Note: In some languages, the definition of a call is made at the procedure level 


and not just at the program level. For these languages, storage for automatic 
variables is associated with the call of the procedure. Every time a 
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procedure is called, a new copy of the variable is gotten. A change to an 
automatic variable remains in effect only while that procedure is called. 
Only the automatic variables in the most recent procedure call can be 
changed. The RCRLVL (recursion level) parameter on the commands applies 
only on a program basis and not on a procedure basis. 


For static variables, the storage is associated with the activation. Only one copy of 
a static variable exists in storage no matter how many times a program is called. A 
change to a static variable remains in effect for the duration of the activation. 


To determine if a program variable is a static or an automatic variable, request an 
intermediate representation of a program (IRP) list (“LIST and *XREF on the 
GENOPT parameter) when the program containing the variables is created. 


When changing a variable that is an array, you must specify one element of the 
array. Consequently, you must specify the subscript values for the array element 
you want to change. 


Using a Job to Debug Another Job 


You may want to use a separate job to debug programs running in another job for 

one of the following reasons: 

* Batch jobs can be debugged by an interactive job. 

* An interactive job can be debugged from another interactive job. This allows one 
display to show debug information without interrupting the application 
program display. 

* An interactive or batch job that is looping can be interrupted and put into debug 
mode. 


Debugging Batch Jobs Submitted to a Job Queue 

Using a separate job to debug another batch job submitted to the job queue allows 

you to put the batch job into debug mode and to set breakpoints and traces before 

the job starts to process. Use the following steps to debug batch jobs to be 
submitted to a job queue: 

1. Submit the batch job using the Submit Job (GSBMJOB) command or a program 
that automatically submits the job with HOLD(*YES). 

SBMJOB HOLD(*YES) 

2. Determine the qualified job name (number/user/name) that is assigned to the 
job using the Work with Submitted Jobs (WRKSBMJOB) command or the Work 
with Job Queues (WRKJOBQ) command. The SBMJOB command also displays 
the name in a completion message when the command finishes processing. 
The WRKJOBQ (Work With Job Queue) command displays all the jobs waiting 
to start in a particular job queue. You can show the job name from this display 
by selecting option 5 for the job. 

3. Enter the Start Service Job (STRSRVJOB) command from the display you plan 
to use to debug the batch job as follows: 

STRSRVJOB JOB(qualified-job-name) 

4. Enter the STRDBG command and provide the names of all programs to be 
debugged. No other debug commands can be entered while the job is waiting 
on the job queue. 

5. Use the Release Job Queue (RLSJOBQ) command to release the job queue. A 
display appears when the job is ready to start, indicating that you may begin 
debugging the job. Press F10 to show the Command Entry display. 
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Use the Command Entry display to enter any debug commands, such as the 
Add Breakpoint (ADDBKP) or Add Trace (ADDTRC) commands. 


Press F3 to leave the Command Entry display, and then press Enter to start the 
batch job. 


When the job stops at a breakpoint, you see the normal breakpoint display. 
When the job finishes, you cannot add breakpoints and traces, or display or 
change variables. However, you can display any trace data using the Display 
Trace Data (DSPTRCDTA) command. 

If you wish to debug another batch job, first end debugging using the End 
Debug (ENDDBG) command and then end servicing the job using the End 
Servicing Job (ENDSRVJOB) command. 


Debugging Batch Jobs Not Started from Job Queues 

Some jobs started on the system are not submitted to a job queue. These jobs 
cannot be stopped before they start running but they can usually be debugged. To 
debug jobs not started from a job queue, do the following: 


1. 


Rename the program that is called when the job starts. For example, if the job 
runs program CUST310, you can rename this program to CUST310DBG. 

Create a small CL program with the same name as the original program (before 
the program was renamed). In the small CL program, use the Delay Job 
(DLYJOB) command to delay for one minute and then use the CALL command 
to call the renamed program. 

Allow the batch job to start to force the CL program to be delayed for one 
minute. 

Use the Work with Active Jobs (WRKACTJOB) command to find the batch job 
that is running. When the display appears, enter option 5 next to the job to 
obtain the qualified job name. 

Enter the Start Service Job (STRSRVJOB) command as follows: 

STRSRVJOB JOB(qualified-job-name) 

Enter STRDBG and any other debug commands, such as the Add Breakpoint 
(ADDBKP) or Add Trace (ADDTRC) command. Proceed with debugging as 
usual. 


Debugging a Running Job 

You can debug a job that is already running if you know what statements the job 
will run. For example, you may want to debug a running program if the job is 
looping or the job has not yet run a program that is to be debugged. The following 
steps allow you to debug a running job: 


ie 


Use the Work with Active Jobs (WRKACTJOB) command to find the job that is 
running. When the display appears, enter option 5 next to the job to obtain the 
qualified job name. 

Enter the Start Service Job (GSTRSRVJOB) command as follows: 

STRSRVJOB JOB(qualified-job-name) 


Enter the Start Debug (STRDBG) command. (Entering the command does not 
stop the job from running.) 


Note: You can use the Display Debug (DSPDBG) command to show the call 
stack. However, unless the program is stopped for some reason, the stack 
is correct only for an instant, and the program continues to run. 


If you know a statement to be run, enter the Add Breakpoint (ADDBKP) 
command to stop the job at the statement. 


If you do not know what statements are being run, do the following: 
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a. Enter the Add Trace (ADDTRC) command. 


b. After a short time, enter the Remove Trace (RMVTRC) command to stop 
tracing the program. 

c. Enter the Display Trace Data (DSPTRCDTA) command to show what 
statements have processed. Use the trace data to determine which data 
statements to process next (for example, statements inside a program loop). 


d. Enter the Add Breakpoint (ADDBKP) command to stop the job at the 
statement. 


5. Enter the desired debug commands when the program is stopped at a 
breakpoint. 


Debugging Another Interactive Job 

You can debug a job from another display, whether the job is running or waiting at 

a menu or command entry display. To debug another interactive job, do the 

following: 

1. Determine the qualified job name of the job to be debugged. To determine the 
name, either enter the Display Job (DSPJOB) command from the display of the 
job to be debugged, or use the Work with Active Jobs (WRKACTJOB) 
command. 


2. Enter the Start Service Job (STRSRVJOB) command using the qualified job 
name. 


3. Enter the Start Debug (STRDBG) command and any other debug commands 
desired. If the job is already running, you may need to enter the Display Debug 
(DSPDBG) command to determine what statement in the program is 
processing. 


When the job being debugged is stopped at a breakpoint, the display station is 
locked. 


Considerations When Debugging One Job from Another Job 
Although most jobs can be debugged from another job, you must take the 
following into consideration: 


* Ajob being debugged cannot be held or suspended (for example, when running 
another group job or a secondary job). 


* When servicing another job with the Start Service Job (STRSRVJOB) command, 
you cannot also debug the job doing the servicing. All debug commands apply 
only to the job being serviced. To debug the job doing the servicing, you must 
either end the servicing of the other job, or have another job service and debug 
Ai 


* Debug commands operate on another job, even if that job is not stopped at a 
breakpoint. For example, if you are debugging a running job and you enter the 
Display Program Variable (DSPPGMVAR) command, the variable you specify is 
shown. Since the job continues to run, the value of the variable may change 
soon after the command is entered. 


* A job being debugged must have enough priority to respond to debug 
commands. If you are debugging a batch job with a low priority and that job 
gets no processing time, then any debug command you issue waits for a 
response from the job. If the job does not respond, the command ends and an 
error message is displayed. 


* You cannot service and debug a job that is debugging itself. However, you can 
service and debug a job that is servicing and debugging another job. 
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Debugging at the Machine Interface Level 


To debug your programs at the machine interface (MI) level, you can specify an MI 
object definition vector (ODV) number for the PGMVAR parameter of a command 
and MI instruction numbers for the STMT parameter of a command. For a 
breakpoint, the system stops at the MI instruction number just as it would at an 
HLL statement number. You must always precede the ODV or MI instruction 
number with a slash (/) and enclose it in apostrophes (for example, '/1A') to 
signal to the system that you are debugging at the MI level. 


The ODV and MI instruction numbers can be obtained from the IRP listing 
produced by most high-level language compilers. Use the *LIST value of the 
GENOPT parameter to produce the IRP listing at program creation time. 


Note: When you debug at the machine interface level, only the characteristics that 
are defined at the machine interface level are available; the HLL 
characteristics that are normally passed to the test environment are not 
available. These HLL characteristics may include: the variable type, number 
of fractional digits, length, and array information. For example, a numeric 
variable in your HLL program may be displayed without the correct decimal 
alignment or possibly as a character string. 


Security Considerations 


To debug a program, you must have *CHANGE authority to that program. The 
*CHANGE authority available by adopting another user’s profile is not considered 
when determining whether a user has authority to debug a program. This prevents 
users from accessing program data in debug mode by adopting another user’s 
profile. 


Additionally, when you are at a user-defined breakpoint of a program that you are 
debugging with adopted user authority, you have only the authority of your user 
profile and not the adopted profile authority. You do not have authorities adopted 
by prior program calls for all breakpoints whether they are added by the Add 
Breakpoint (ADDBKP) command or are caused by an unmonitored escape 
message. 


Using COPY, SAVE, RESTORE, CRTDUPOByJ, and CHKOBJITG 
while Debugging 

Breakpoints or statement traces may be temporarily removed from a program 
while the debug function is running if you use certain control language (CL) 
commands to specify your library or program. Breakpoints and statement traces 
are restored when the CL command completes running. A CPD190A message is in 
the job log when the breakpoints or traces are removed; another CPD190A message 
is in the job log when the breakpoints and statement traces are restored. 


Breakpoints or statement traces may be temporarily removed from a program 
when you use the following CL commands to specify your library: 


CHKOBJITG CPY CPROBJ RSTLIB SAVLIB 
CPYLIB CRTDUPOBJ RSTOBJ SAVOBJ 
SAVSYS 

SAVCHGOBJ 


Note: When the CL commands are running on your program, you may not be able 
to add breakpoints or add traces to the program. If you enter the Add 
Breakpoint (ADDBKP) command or the Add Trace (ADDTRC) command 
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when any of the commands are running on your program, you will receive 
error message CPF7102. 
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Appendix A. TFRCTL Command 


The Transfer Control (TFRCTL) command calls the program specified on the 
command, passes control to it, and removes the transferring program from the call 
stack. Reducing the number of programs on the call stack can have a performance 
benefit. When a CALL command is used, the program called returns control to the 
program containing the CALL command. When a TFRCTL command is used, 
control returns to the first program in the call stack. The first program then 
initiates the next sequential instruction following the CALL command. 


Note: The TRFCTL command is not valid in ILE CL procedures. 


Using the TFRCTL Command 


In the following illustration, if Program A is specified with USRPRF(*OWNER), the 
owner’s authorities are in effect for all of the programs shown. If Program B is 
specified with USRPRF(*OWNER), the owner’s authorities are in effect only while 
Programs B and C are active. When Program B transfers control to Program D, 
Program B is no longer in the call stack and the owner of Program B is no longer 
considered for authorization during the running of Program D. When the 
programs complete processing (by returning or transferring control), the owner’s 
authorities are no longer in effect. Any overrides issued by Program B remain in 
effect while Program D is running and are lost when Program D does a return. 


Program A -—————»Program B 
Program C 
CALL PGMB CALL PGMC—+ ; 
ae < RETURN 
TFRCTL PGMD > Program D 
RETURN 
RBAFN546-0 


The TFRCTL command has the following format: 
TFRCTL PGM(library-name/program-name) PARM(CL-variable) 


The program (and library qualifier) may be a variable. 


It is important to note that only variables may be used as parameter arguments on 
this command, and that those variables must have been received as a parameter in 
the argument list from the program that called the transferring program. That is, 
the TFRCTL command cannot pass a variable that was not passed to the program 
running the TFRCTL command. 
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In the following example, the first TRFCTL is valid. The second TFRCTL command 
is not valid because &B was not passed to this program. The third TFRCTL 
command is not valid because a constant cannot be specified as an argument. 

PGM PARM(&A) 

DCL &A *DEC 3 

DCL &B *CHAR 10 

IF (&A *GT 100) THEN (TFRCTL PGM(PGMA) PARM(&A)) /* valid = */ 

IF (&A *GT 50) THEN (TFRCTL PGM(PGMB) PARM(&B)) /* not valid */ 

ELSE (TFRCTL PGM(PGMC) PARM('1')) /* not valid */ 

ENDPGM 


The PARM parameters are discussed under Passing Parameters hetween Programs) 


Passing Parameters 


The TFRCTL command can be used to pass parameters to the program being 
called in the same way the CALL command passes parameters, but with these 
restrictions: 


* The parameters passed must be CL variables. 


* The CL variables passed by the transferring program must have been received as 
parameters by that program. 


* This command is valid only within OPM CL programs. 


In the following example, PROGA calls PROGB and passes two variables, &A and 
&B, to it. PROGB uses these two variables and another internally declared variable, 
&C. When control is transferred to PROGC, only &A and &B can be passed to 
PROGC. When PROGC finishes processing, control is returned to PROGA, where 
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these variables originated. 


PROGA 7» PROGB 


PGM PGM (&A &B) 

DCL &A DCL &A *DEC 

DCL &B DCL &B *DEC 

DCL &C *DEC 

CHGVAR &C (&A + &B) 

; CHGVAR &A (&A - 2) 
CALL PROGB (&A &B) IF (&A\ = 3) GOTO LABEL 
.< TFRCTL PROGC (8A &B) 
LABEL: RETURN 

ENDPGM 


ENDPGM 


> PROGC 


PGM (&A &B) 

DCL &A *DEC 

DCL &B *DEC 

CHGVAR &B (&B - 8&A 
RETURN 

ENDPGM 


RBAFN547-0 
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Appendix B. Job Log Output Files 


Directing a Job Log 


You can direct the job log for a job to one or two database files with the Control 
Job Log (QMHCTILJL) API or the Display Job Log (DSPJOBLOG) command. The 
first file is the primary job log file. This file contains the essential information for a 
message, such as, message ID, message type, and message severity. One record is 
produced in the primary job log file for each message selected for processing. The 
second file is the secondary job log file. The production of this file is only possible 
by using QMHCTLJL API; however, it is also optional. 


The secondary job log file contains the first and second level text for a message. 
The text is in print format. Any message data is merged with the message 
description and the result is formatted into one or more print lines. For each 
message selected for processing there can be more than one record in the 
secondary job log file; one record for each first and second level print line. 


Records in the primary file can be related to records in the secondary file through 
use of the Message Reference Key. Each record placed in the primary file contains 
a field that is the Message Reference Key (MRK) of the related message. Similarly, 
each secondary file record contains the MRK of the related message. The MRK for 
a message is unique within the context of a job. Once the MRK of a primary file 
record is known, the related secondary records can be readily identified since only 
these secondary records will contain the same MRK value. 


Model for the Primary Job Log 


The IBM supplied model for the primary job log file is QAMHJLPR in library 
QSYS. The primary record format is QMHPFT. A detailed description of this 
format follows: 


Field Length in 

Order Field Name Data Type Bytes Field Description 
1 QMHJDT DATE 10 Date job log created 
2 QMHJTM TIME 8 Time job log created 
3 QMHMRK CHAR 4 Message reference key 
4 QMHTYP CHAR 10 Message type 
5 QMHSEV BIN 4 Message severity 
6 QMHMID CHAR vi Message ID 
7 QMHDAT DATE 10 Message sent date 
8 QMHTIM TIME 8 Message sent time 
9 QMHMEF CHAR 20 Message file name 
10 QMHRPY CHAR 4 Reply reference key 
Hit QMHRQS CHAR 1 Request Message Status 
12 QMHSTY CHAR 1 Sending program type 
13 QMHRTY CHAR 1 Receiving program type 
14 QMHSSN BIN 4 Number of statements for sending 

program 
15 QMHRSN BIN 4 Number of statements for 
receiving program 

16 QMHCID BIN 4 CCSID of the message data or 


immediate message 
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17 
18 
19 
20 
21 
22 


23 
24 
25 
26 
27 


28 
29 
30 
31 
32 
33 


34 
35 


Field Length in 


Order Field Name Data Type Bytes Field Description 

QMHPRL CHAR 1 Message percolated indicator 

QMHSPR VAR CHAR 256 MAX Sending procedure name 

QMHSMD CHAR 10 Sending module name 

QMHSPG CHAR 12 Sending program name 

QMHSLB CHAR 10 Sending library name 

QMHSTM CHAR 30 Statement number(s) for sending 
program 

QMHRPR VAR CHAR 256 MAX Receiving procedure name 

QMHRMD CHAR 10 Receiving module name 

QMHRPG CHAR 10 Receiving program name 

QMHRLB CHAR 10 Receiving program library name 

QMHRTM CHAR 30 Statement number(s) for receiving 
program 

QMHSYS CHAR 8 System name 

QMHJOB CHAR 26 Qualified Job name 

QMHMDT VAR CHAR 3000 MAX Message data or immediate 
message 

QMHCSP VAR CHAR 4096 MAX Complete sending procedure 
name 

QMHCRP VAR CHAR 4096 MAX Complete receiving procedure 
name 

QMHLSP VAR CHAR 6144 MAX Long sending program name 

QMHTID CHAR 8 Thread 

QMHMSC ZONED 6,0 Microseconds 


The definition of the fields in this record are as follows: 


QMHJDT 


Date job log created; DATE(10) 


The date the production of the job log began. The field is a date field in the 
database record. The format of the date is *ISO. A value in this date field is in 
the format yyyy-mm-dd. Each record produced for the same job log will have 
the same value in this field. 


QMHJTM 


Time job log create; TIME(8) 


The time the production of the job log began. This field is defined as a time 
field in the database record. The format of the time is defined to be *ISO. A 
value in this time field is in the format hh.mm.ss. Each record produced for the 
same job log will have the same value in this field. 


QMHMRK 


Message reference key; CHAR(4) 


The message reference key the related message had in the job message queue. 
The records are placed in the primary database file in strictly ascending 
sequence by message reference key. Within the set of records produced for a 
single job log, this field is unique for each record and thus can be used as a 
unique key for the record. If the records for two or more job logs are placed 
into the same member, the key may no longer be unique. 


QMHTYP 


Message type; CHAR(10) 


The message type of the related message. One of the following special values 
will appear in this field: 
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*CMD Commands that are logged from the execution of a CL program. 


*COMP 
Completion message type. 


*COPY 
Sender’s copy message type. 


*DIAG 
Diagnostic message type. 


*ESCAPE 
Escape message type. 


*INFO 

Information message type. 
*INQ Inquiry message type. 
*NOTIFY 

Notify message type. 
*ROS Request message type. 
*RPY Reply message type. 


QMHSEV 
Message severity; BIN(4) 


The severity the message has. This is a value from 0 through 99. 


QMHMID 
Message ID; CHAR(7) 


The message ID for the message. This field will contain the special value 
*IMMED if the message is an immediate message which has no message ID. 


QMHDAT 
Message sent date; DATE(10) 


The date the message was sent. This field is defined as a date field in the 
database record. The format of the date is *ISO. A value in this field is in the 
format yyyy-mm-dd. 


QMHTIM 
Message sent time; TIME(8) 


The time the message was sent. The field is defined as a time field in the 
database record. The format of the time is defined to be *ISO. A value in this 
field is in the format hh.mm.ss. 


QMHMFEF 
Message File; CHAR(20) 


The name of the message file that is to be used to obtain the message 
description for the message. The first 10 characters of the field contain the 
message file name. The second 10 characters contain the library name. If the 
field QMHMID contains *IMMED to indicate an immediate message, this field 
will contain all blanks. 


QOMHRPY 
Reply reference key; CHAR(4) 


* If the message type of the message is inquiry, notify, or sender’s copy, this is 
the message reference key of the related reply message. 
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* If there is no reply message available this field will contain a null value 
(’00000000’X). 


* If the message type is not inquiry, notify, or sender’s copy, this field will also 
contain a null value. 


In order to maintain the strictly ascending sequence by message reference key, 
the record for the reply message may not immediately follow the record for the 
inquiry, notify, or sender’s copy message. 


QMHROS 
Request Message Status; CHAR(1) 
* If the message type is *RQS, this is an indicator which shows whether the 
request message was run or not. 


* If the indicator is set to zero (‘FO’X) the request was not run. 
* If the indicator is set to one (’F1’X) the request was run. 


If the messages type is not *RQS, this indicator will always be zero. 


QMHSTY 
Sending program type; CHAR(1) 


An indicator with the following values that shows whether the sending 
program was an OPM program or an ILE program. 


* If this indicator is set to zero (’F0’X), the sending program is an OPM or 
System Licensed Internal Code (SLIC) program with a name less than or 
equal to 12 characters. The program name is placed in fields QMHSPG and 
QMHLSP. 


* If the indicator is set to one (’F1’X), the sending program is an ILE program 
with a procedure name less than or equal to 256 characters. The procedure 
name is placed in fields QMHSPR and QMHCSP. 


* If the indicator is set to two (’F2’X), the sending program is an ILE program 
with a procedure name greater than 256 characters and up to 4096 
characters. The complete sending sending procedure name is in field 
OMHCSP; field QMHSPR is blank. 


* If the indicator is set to three (’F3’X), the sending program is a SLIC 
program with a name greater than 12 characters and up to 256 characters. 
The complete sending program name is in field QMHLSP; field QMHSPG is 
blank. 


QMHRTY 
Receiving program type; CHAR(1) 


An indicator with the following values that shows the type of the receiving 

program: 

* If this indicator is set to zero (‘FO’X), the receiving program was an OPM 
program. The program name is placed in field QMHRPG. 

* If the indicator is set to one (’F1’X), the receiving program was an ILE 
program with a procedure name less than or equal to 256 characters. The 
procedure name is placed in fields QMHRPR and QMHCRP. 

* If the indicator is set to two (’F2’X), the receiving program is an ILE 
program with a procedure name greater than 256 and up to 4096 characters. 
The entire receiving procedure name is placed field QMHCRP; the field 
QMHRPR is blank. 


QMHSSN 
Number of statements for sending program; BIN(4) 
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The number of statement numbers for sending program. 
* If the sending program type field QMHSTY contains a zero (’FO’X) or a three 
(‘F3’X), this field contains a value of 0 or 1. 


* If the sending program type field contains a one (’F1’X) or a two (’F2’X), this 
field can contain the value 0, 1, 2, or 3. 


The value provided in this field defines how many statement numbers are in 
the field QMHSTM. 


QMHRSN 
Number of statements for receiving program; BIN(4) 


The number of statement numbers for receiving program. 


* If the receiving program type field QMHRTY contains a zero (’FO’X), this 
field contains a value of 0 or 1. 

* If the receiving program type field contains a one (’F1’X) or a two (’F2’X), 
this field contains the value 0, 1, 2, or 3. The value provided in this field 
defines how many statement numbers are in the field QMHRTM. 


QMHCID 
CCSID of message data; BIN(4) 


The CCSID of the message data or immediate message that is contained in the 
field QMHMDT. 


QMHPRL 
Message percolate indicator; CHAR(1) 


An indicator that shows whether the message was percolated to the receiving 
program or not. 


* If the message was not percolated this field contains a zero (’FO’X). 
* If the message was sent this field contains a one (’F1’X). 


Message percolation can only occur within an ILE program. Therefore, this 
field contains a one only if the receiving program type field QMHRTY contains 
a one (’F1’X) or a two (’F2’X). 


QMHSPR 
Sending procedure name; VAR CHAR(*) 


* If the sending program type field QMHSTY contains a zero (’FO’X) or three 
(‘F3’X), this field contains the value *N. 


* If the sending program type field QMHSTY contains a one (’F1’X), this field 
contains the sending ILE procedure name. The name can be a maximum of 
256 characters in length. 


* If the sending program type field QMHSTY contains a two (’F2’X), this filed 
contains blanks, while the entire name will be contained in the field 
QMHCSP. 


This field can contain a nested procedure name for a sending program type of 
one (’F1’X) or two (’F2’X); each procedure name is separated by a colon. The 
outer-most procedure name is identified first and is followed by the 
procedures contained in it. The inner-most procedures are identified last in the 
string. 

QMHSMD 
Sending module name; CHAR(10) 


* If the sending program type field QMHSTY contains a zero (’FO’X) or a three 
(‘F3’X), this field contains the value *N. 
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* If the sending program type field QMHSTY contains a one (’F1’X) or a two 
(‘F2’X), this field contains the sending ILE module name. 


QMHSPG 

Sending program name; CHAR(12) 

* If the sending program type field QMHSTY contains a zero (’FO’X), a one 
(‘F1’X), or a two (’F2’X), the field contains the program name from which the 
message was sent. 

* If the sending program type is a three (’F3’X), this field contains blanks and 
field QMHLSP contains the sending program name. 


QMHSLB 
Sending library name; CHAR(10) 


The name of the library that the sending program was contained in. 


QMHSTM 
Statement number(s) for sending program; CHAR(30) 


The statement number(s) at which the sending program sent the message. Each 
statement number is 10 characters in length. 


* If the sending program type field QMHSTY contains a zero (’FO’X) or a three 
('F3’X), there is, at most, one statement number in the first 10 characters. 
That statement number represents an MI instruction number. The number is 
a hexadecimal number. 


* If the sending program type field contains a one (’F1’X) or a two (’F2’X), this 
field can contain statement numbers of 0, 1, 2, or 3. The field QMHSSN 
specifies how many there are. In this case, a statement number is a higher 
level language statement number and not an MI instruction number. Each 
number is a decimal number. 


QOMHRPR 

Receiving procedure name; VAR CHAR(*) 

* If the receiving program type field contains a zero (’FO’X), this field contains 
the value *N. 

* If the Receiving program type field QMHRTY contains a one (’F1’X), this 
field contains the receiving ILE procedure name. The name can be a 
maximum of 256 characters in length. 

* If the Receiving program type field QMHRTY contains a two (’F2’X), this 
field contains blanks, while the entire name will be contained in the field 
QMHCRP. 


This field can contain a nested procedure name for a sending program type of 
1 or 2; each procedure name is separated by a colon. The outer-most procedure 
name is identified first and is followed by the procedures contained in it. The 
inner-most procedures are identified last in the string. 


QMHRMD 
Receiving module name; CHAR(10) 


* If the receiving program type field contains a zero (’OF’X), this field contains 
the value *N. 


* If the receiving program type field QMHRTY contains a one (’F1’X) or a two 
(‘F2’X), this field contains the receiving ILE module name. 


QMHRPG 
Receiving program name; CHAR(10) 
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The program name of the OPM or ILE program to which the message was 
sent. 


QMHRLB 
Receiving library name; CHAR(10) 


The name of the library that the receiving program was in. 


QMHRTM 
Statement number(s) for receiving program; CHAR(30) 


The statement number(s) at which the receiving program was stopped when 
the message was sent. Each statement number is 10 characters in length. 


* If the receiving program type field QMHRTY contains a zero (‘FO’X), there is, 
at most, one statement number in the first 10 characters. That statement 
number represents an MI instruction number. The number is a hexadecimal 
number. 


For any other value of the receiving program type, there can be 0, 1, 2, or 3 
statement numbers in this field. The field QMHRSN specifies how many there 
are. In this case, a statement number is a higher level language statement 
number and not an MI instruction number. Each number is a decimal number. 


QMHSYS 
System name; CHAR(8) 


The name of the system that the job log was produced on. 


QMHJOB 
Qualified job Name; CHAR(26) 


The fully qualified name of the job for which the message is being logged for. 
The first 10 positions contain the job name, the next 10 positions the user 
name, and the last six positions the job number. 


QMHMDT 
Message data; VAR CHAR(*) 


If the field QMHMID contains the special value *IMMED, this field contains an 
immediate message. Otherwise, this field contains the message data that was 
used when the message was sent. This field can contain a maximum of 3000 
characters. If the immediate message or message data is longer, it is truncated 
to 3000 characters. 


If the message data contains pointers, the pointers is invalidated before the 
message data is written to the database file. 


QMHCSP 
Complete sending procedure name; CHAR(VAR) 
* If the sending program type is zero (’FO’X) or three (’F3’X), this field 
contains blanks. 
* If the sending program type is one (’F1’X) or two (’F2’X), this field contains 
the entire ILE procedure name. The name can be a maximum of 4096 
characters in length. 


This field can contain a nested procedure name where each procedure name 
is separated by a colon. The outer-most procedure name is identified first 
and is followed by the procedures contained in it. The inner-most 
procedures are identified last in the string. 


QMHCRP 
Complete receiving procedure name; CHAR(VAR) 
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* If the sending program type is zero (’F0’X), this field contains blanks. 


* If the receiving program type is one (’F1’X) or two (’F2’X), this field contains 
the entire ILE procedure name. The name can be a maximum of 4096 
characters in length. 

The field can contain a nested procedure name where each procedure name 
is separated by a colon. The outer-most procedure name is identified first 
and is followed by the procedures contained in it. The inner-most 
procedures are identified last in the string. 


QMHLSP 
Long sending program name; CHAR(VAR) 


This field contains the entire sending program name from which the message 
was sent for all sending program types. The name can be a maximum of 6144 
characters in length. 


QMHTID 
Thread; CHAR(8) 


This field identifies the thread within the job that sent the message. 


QMHMSC 
Microseconds; ZONED(6,0) 


This is the microseconds part of the time the message was sent. It can be used 
to determine with more precision the time the message was sent. 


The IBM supplied model for the secondary job log file is QAMHJLSC in library 
QSYS. The secondary record format name is QMHSFT. A detailed description of 
the secondary record format follows: 


Field Order Field Name Data Type Length in Bytes Field Description 
1 QMHJDS DATE 10 Date job log created 
2 QMHJTS TIME 8 Time job log created 
3 QMHMKS CHAR 4 Message reference key 
7 QMHSYN CHAR 8 System name 
8 QMHJBN CHAR 26 Qualified job name 
4 QMHLNN BIN 4 Message line number 
5 QMHSID BIN 4 CCSID of text line 
6 QMHTTY CHAR 1 Message text indicator 
9 QMHLIN CHAR 78 Message text line 


The length of the field indicates the number of total bytes for the field. 


The definition of the fields in this record are as follows: 


QMHJDS 
Date job log created; DATE(8) 
The date the production of the job log began. The field is a date field in the 
database record. The format of the date is *ISO. A value in this field is in the 
format yyyy-mm-dd. Each record produced for the same job log will have the 
same value in this field. 

QMHJTS 
Time job log created; TIME(8); 


The time the production of the job log began. This field is defined as a time 
field in the database record. The format of the time is defined to be *ISO. A 


400 08/400 CL Programming V5R2 


value in this field is in the format hh.mm.ss. Each record produced for the 
same job log will have the same value in this field. 


QMHMKS 
Message reference key; CHAR(4) 


The message reference key the related message had in the job message queue. 
The records are placed in the secondary database file in ascending sequence by 
message reference key. There can be more than one secondary record for a 
specific message reference key. This field also exists in the related primary 
record. Therefore, once the message reference key is obtained from a primary 
record, it can be used to read the related records from the secondary file. 


QMHSYN 
System name; CHAR(8) 


The name of the system that the job log was produced on. 


QMHJBN 
Qualified job Name; CHAR(26) 
The fully qualified name of the job for which the message is being logged for. 


The first 10 positions contain the job name, the next 10 positions the user 
name, and the last six positions the job number. 


QMHLNN 
Message line number; BIN(4) 


The line number of the line within the text type. For both the first and second 
level text, the line number starts at one for the first line of the text and is 
incremented by one for each additional line within that level. 


QMHSID 
CCSID of message text line; BIN(4) 


The CCSID of the message text line that is contained in field QMHLIN. 


QMHTTY 
Message text type; CHAR(1) 


An indicator which specifies whether field QMHLIN contains a line of the first 
or second level text. This field will contain one of the following values: 


1 Field QMHLIN contains first level text. 
2 Field QMHLIN contains second level text. 
QMHLIN 


Message text line: CHAR(78) 


This field contains one line of the first or second level text. 
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Appendix C. IBM-Supplied Libraries in Licensed Programs 


(LP) 


The iSeries server contains the definitions of many libraries. They provide a 
method to organize most of the objects that are stored on the system. 


In the following tables, the IBM-supplied libraries display in alphabetical order 
under the licensed program (LP) that provided them. 


that are supp 


System/400 (OS/400) licensed program. 


lied for use 


with 


e base operating system, the Operating 


shows the libraries supplied for all the other iSeries licensed programs. 


— The licensed programs appear alphabetically by the full descriptive name of 
each program. They display on the Install Licensed Programs menu on the 


system. 


— Also, if there are features in a licensed program, the feature name and 
number precede the libraries that are contained in that feature. 


IBM-Supplied Libraries for the OS/400 Licensed Program 


Table 11. IBM-Supplied Libraries for the OS/400 Program 


Program Name 


Library Name 


Operating System/400 (5722-SS1) 


© Copyright IBM Corp. 1997, 2002 


QCCA 
QCLUSTER 
QDB2MS 
QDNS 
QDOC 


QDOCunnn 


QDSNX 


QFNTCPL 
QFNTWT 
QFPNTWE 
QGDDM 


QGPL 
QGPLTEMP 


QHLPSYS 


Purpose of Library 


CCA cryptopgraphic service provider 
HA switchable resources 

DB2® multisystem 

Domain name system 

Contains document library objects 
residing in the system auxiliary storage 
pool (ASP), ASP 1. Document library 
services (DLS) system objects reside here. 
Not shipped with system; created at IPL 
time. 

Contains document library objects 
residing in user auxiliary storage pools 
(ASP). nnnn is the number, 0002 through 
0016, of the ASP. Not shipped with 
system; created at IPL time. 

Not shipped with system; created at 
install time 

AFP* compatibility fonts 

Additional fonts 

NetWare enhanced integration 

Support for graphical data display 
manager (GDDM*) and presentation 
graphics routines (PGR) 

General purpose library of the user 

Not shipped with system; created at 
install time 

Online documentation for some system 
functions 
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OS/400 Libraries 


Table 11. IBM-Supplied Libraries for the OS/400 Program (continued) 


Program Name 


Libraries for System/36 Environment 
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Library Name 
QICSS 

QICU 

QIWS 

QJRNL 
QMGU 


QMSE 


QMU400 
QPASE 
QPFRDATA 


QOALIB 
QRCL 


QRECOVERY 
ORPLOBJ 
OSCXxxxxxx 


QSHELL 
QSMP 
QSOC 
QSPL 
QSR 
QSRV 
QSYS 
QSYS2 
QSYSCGI 
QSYSDIR 
QSYSINC 
QSYSLOCALE 


QSYSNLS 
QOSYSVxRxMx 


QSYS2 


QSYSxxxx 
QTEMP 
QUMEDIA 
QUSRINFSKR 


QUSRSYS 
QUSRTEMP 


QUSRTOOL 


QSSP 
QS36F 


Purpose of Library 

Digital Certificate Manager 
International components for Unicode 
Host servers 

HA journal performance 

System/36 and System/38 migration 
utility 

Media and Storage Extensions (MSE) 
library 

System/36 Migration Assistant 
Portable app solutions environment 
Library of system-collected performance 
data 

Question-and-answer utility library 
Library for reclaiming objects via the 
RCLSTG command 

System recovery library 

Library for replaced objects 

Data library for collecting APAR data; 
XXXxxxx = last 7 digits of the problem 
identifier 

Qshell 

DB2 symmetric multiprocessing 
OptiConnect 

Spooling library 

Object Connect 

System service library 

System library 

Extended base support 

Extended base directory support 
Extended base directory support 
System openness includes 

Contains locale source members for use 
in creating “LOCALE objects. 

Extended NLS support 

iSeries CL compiler library, previous 
release support; x identifies the version, 
release, and modification level of the 
previous release. 

Supplemental system library for objects 
whose names do not begin with the letter 
Q; includes, for example, objects for CPIs. 
Online information. 

Temporary library of user 

Ultimedia system facilities 

Bookmarks for InfoSeeker books. Created 
at install time. 

Additional IBM-supplied objects 

Not shipped with system; created at 
install time 

Example tools 


System/36 environment library 
System/36 environment file library; 
created by system 
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Table 11. IBM-Supplied Libraries for the OS/400 Program (continued) 


Program Name Library Name Purpose of Library 
#CGULIB System/36 Character Generator Utility 
(CGU) 
#DFULIB System/36 Data File Utility (DFU) 
#DSULIB System/36 Development Support Utility 
(DSU) 
#LIBRARY System/36 environment, general purpose 
library of user 
#SDALIB System/36 Screen Design Aid (SDA) 
#SEULIB System/36 Source Entry Utility (SEU) 
Library for System/38 Environment 
QSYS38 System/38 environment library 


IBM-Supplied Libraries for Other iSeries Licensed Programs 


Table 12. Libraries for Other LPs on the iSeries server 


Program Name Library Name Purpose of Library 
Advanced DBCS Printer Support for iSeries (5722-AP1) 
QAPS Advanced double-byte character set 
(DBCS) printer support 
QAPS2 Advanced DBCS Printer Support for 


AS/400-IPDS 
Advanced Function Printing DBCS Fonts for AS/400 (5769-FN1) 


TM 


QFNT60 AFP DBCS Fonts/400-Base Support 

Library for: Japanese Fonts 

QFNT61 AFP DBCS Fonts /400-Japanese 

Library for: Korean Fonts 

QFNT62 AFP DBCS Fonts /400-Korean 

Library for: Traditional Chinese Fonts 

QFNT63 AFP DBCS Fonts/400-Traditional 
Chinese 

Library for: Simplified Chinese Fonts 

QFNT64 AFP DBCS Fonts/400-Simplified 
Chinese 

Library for: Thai Fonts 

QFNT65 AFP DBCS Fonts/400-Thai 

Advanced Function Printing Fonts for AS/400 (5769-FNT) 
QFNT00 OS/400 Base support for AFP fonts 
QFNT01 OS/400 Sonoran Serif** font support 


(Sonoran Serif is a functional 
equivalent of Monotype Times New 


Roman**) 
QFNT02 OS/400 Sonoran Serif Headliner font 
QFNT03 OS/400 Sonoran Sans Serif** font 


support (Sonoran Sans Serif is a 
functional equivalent of Monotype 


Arial**) 

QFNT04 OS/400 Sonoran Sans Serif Headliner 
font 

QFNT05 OS/400 Sonoran Sans Serif Condensed 
font 

QFNT06 OS/400 Sonoran San Serif Expanded 
font 

QFNT07 OS/400 Monotype Garamond™ font 

QFNT08 OS/400 Century Schoolbook** font 
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LP Libraries 


Table 12. Libraries for Other LPs on the iSeries server (continued) 


Program Name Library Name Purpose of Library 
QFNT09 OS/400 Pi and special characters font 
QFNT10 OS/400 ITC Souvenir** font 
QFNT11 OS/400 ITC Avant Garde Gothic** font 
QFNT12 OS/400 Math and Science font 
QFNT13 OS/400 DATA1 font 
QFNT14 OS/400 APL2® font 
QFNT15 OS/400 OCR A and OCR B fonts 
Advanced Job Scheduler for iSeries (5722-JS1) 
QS Job Scheduler 
AFP Utilities for iSeries (5722-AF1) 
QAFP AFP Utilities for iSeries 
Application Program Driver for AS/400 (5722-PD1) 
QAPD Application Program Driver/400 
Backup Recovery and Media Services for iSeries (5722-BR1) 
QBRM BRM Services/400 support 
QUSRBRM BRM Services/400 user data 
Q1ABRMSFnn Save file libraries per ASP(nn) 
Business Graphics Utility for AS/400 (5722-DS1) 
QBGU AS/400 Business Graphics Utility 
(BGU) 
CICS Transaction Server for iSeries (5722-DFH) 
QCICS CICS/400® 
QCICSSAMP Sample CICS® application programs 
Communications Utilities for AS/400 (5722-CM1) 
ORJE Remote job entry (RJE) and VM/MVS 
bridge 
Content Manager for iSeries (5722-VI1) 
OVI Content Manager for iSeries 
Content Manager OnDemand for iSeries (5722-RD1) 
QRDARS OnDemand 
QUSRRDARS OnDemand user data 
QUSROND OnDemand user data 
Cryptographic Access Provider 128-bit (5722-AC3) 
QCAP3 Cryptographic Access Provider 128-bit 
Cryptographic Support for AS/400 (5722-CR1) 
QCRP Cryptographic Support for AS/400 
DataPropagator Relational V8 for iSeries (5722-DP4) 
QDPR DB2 DataPropagator 
DB2 Query Manager and SQL Development Kit for iSeries (5722-ST1) 
QSOQL Structured Query Language/400 
(SQL/400) 
DB2 Universal Database Extenders for iSeries V7.2 (5722-DE1) 
QDBEX DB2 UDB Extenders 
QDBXM (option 2) XML Extender 
QDB2TX (option 1) Text Extender 
QIMO (option3) Text Search Engine 
DCE Base Services for AS/400 (5769-DC1) 
QDCE2 DCE Base Services for AS/400 
DCE DES Library Routines for AS/400 (5769-DC3) 
QDCEE DCE DES Library Routines 
QDCE2 DCE Base Services for AS/400 
Developer Kit for Java (5722-JV1) 
QJAVA Developer Kit for Java 
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Table 12. Libraries for Other LPs on the iSeries server (continued) 


Program Name Library Name 


HTTP Server for iSeries (5722-DG1) 
QHTTPSRV 
QTCM 

ILE C (5722-WDS) 
QCLE 


QCPPLE 
ILE C++ (5722-WDS) 

QCPPLE 

OCXXN 
ILE COBOL (5722-WDS) 

QCBLLE 

QCBLLEP 


QLBL 
#COBLIB 
OCBL 
ILE RPG (5722-WDS) 
QRPG 
QRPGLE 
QRPGLEP 
#RPGLIB 
QRPG38 
Infoprint Server for iSeries (5722-IP1) 
QIPS 
iSeries Access (5722-XW1) 
QCA400W 
iSeries Access for Windows (5722-XE1) 
QCAEXP 
iSeries Access for Web (5722-XH1) 
QIWA 
iSeries Access for Wireless (5722-XP1) 
QIWR 


iSeries Client Encryption (128-bit) (5722-CE3) 


QCE3 


iSeries Integration for Windows Server ( 5722-WSV) 


QNTAP 


Managed System Services for iSeries (5722-MG1) 


QSVMSS 


QSVDSTRPS 


Performance Tools for iSeries (5722-PT1) 
QPFR 

Query for iSeries (5722-QU1) 
QORYLIB 


System/38 Utilities for AS/400 (5722-DB1) 


QIDU 


System Manager for iSeries (5722-SM1) 
QSMU 


TCP/IP Connectivity Utilities for iSeries (5722-TC1) 


QTCP 


Purpose of Library 


Go Webserver for AS/400 
Triggered Cache Manager 


Integrated Language Environment® 
C/400 
ILE C 


ILE C++ 
ILE C++, previous release support 


ILE COBOL /400 library 

ILE COBOL/400, previous release 
support 

OPM COBOL 
System/36-compatible COBOL 
System/38-compatible COBOL 
RPG/400 

ILE RPG/400 

ILE RPG/400, previous release support 
System/36-compatible RPG II 
System/38-compatible RPG III 
Infoprint Server 

iSeries Access Base 

iSeries Access for Windows 
iSeries Access for Web 

iSeries Access for Wireless 

Client Encryption 128-bit 
Integration for Windows Server 
SystemView® Managed System 
Services /400 

SystemView distribution repository for 
user objects; created when LP is 
installed 

Performance Tools for iSeries 


Query for iSeries 


System/38 Query, Text Management, 
and Data File Utility (DFU) 


SystemView System Manager /400 


TCP/IP Connectivity Utilities /400 
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LP Libraries 


Table 12. Libraries for Other LPs on the iSeries server (continued) 


Program Name Library Name Purpose of Library 
Toolbox for Java (5722-JC1) 
QJT400 Toolbox for Java 
VisualAge Generator Server for AS/400 (5769-VG1) 
OVGEN VisualAge Generator Server 
QGPL General purpose library of the user 
WebSphere Development Studio (5722-WDS) 
QPDA Includes the following tools and 
utilities: 


¢ APF (advanced printer function) 


* CGU (character generator utility), 
for DBCS systems only 


¢ DFU (data file utility) 
* ISDB (interactive source debugger) 


* PDM (programming development 
manager) 


* RLU (report layout utility) 
* SDA (screen design aid) 


* SEU (source entry utility) 
QADM Application development manager 
PP 1 8 
QDMT Application dictionary services 
PP y 
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Appendix D. Abbreviations of CL Commands and Keywords 


This section contains alphabetic lists of abbreviations that are used in CL 
commands that are part of IBM OS/400 and other IBM iSeries licensed programs. 


This information can assist you in naming commands and keywords in a 
consistent manner when using command definition. (See 

and the article on command definition statements in the 
CL section of the Programming category in the iSeries Information Center. 


CL Command Verb Abbreviations 


Most CL command names follow a consistent naming style. The first three letters 
of the command name represent the action that is being performed. The remaining 
letters of the command name describe the object that is having the action 
performed on it. 


Another name for the three-letter command prefix is the command ‘verb’. The 
majority of all CL commands use one of the following common command verbs: 


Verb Abbreviation Meaning 
ADD add 

CHG change 
CRT create 
DLT delete 
DSP display 
END end 

RMV remove 
STR start 

WRK work with 


The following is a list of all the abbreviations that are used as command verbs: 


Verb Abbreviation Meaning 
ADD add 

ALC allocate 
ALM alarm 
ANS answer 
ANZ analyze 
APY apply 
ASK ask 

BLD build 
CFG configuration 
CHG change 
CHK check 
CLO close 
CLR clear 
CMP compare 
CNL cancel 
CPH cipher 
CPR compress 
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Verb Abbreviation 


CPY 
CRT 
CVT 
DCP 
DLC 
DLT 
DLY 
DMP 
DSC 
DSP 
DUP 
EDT 
EJT 
EML 
ENC 
END 
EXP 
EXT 
FIL 
FMT 
FND 
GEN 
GRT 
HLD 
IMP 
INS 
INZ 
LNK 
LOD 
MGR 
MON 
MOV 
MRG 
OPN 
ORD 
OVR 
PAG 
PKG 
POS 
PRM 
PRT 
PWR 
ORY 
RCL 


Meaning 


copy 
create 


convert 
decompress 
deallocate 
delete 
delay 
dump 
disconnect 
display 
duplicate 
edit 
eject 
emulate 
encipher 
end 
export 
extract 
file 
format 
find 
generate 
grant 
hold 
import 
install 
initialize 
link 
load 
migrate 
monitor 
move 
merge 
open 
order 
override 
paginate 
package 
position 
promote 
print 
power 
query 
reclaim 
receive 
reorganize 
release 
remove 
rename 
replace 
request 
reroute 
resume 
restore 
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Abbreviations of CL Commands and Keywords 


Verb Abbreviation 


RTV 
RUN 
RVK 
SAV 
SBM 
SET 
SLT 
SND 
STR 
TFR 
TRC 
UPD 
VFY 
VRY 
WRK 


Meaning 


retrieve 
run 
revoke 
save 
submit 
set 
select 
send 
start 
transfer 
trace 
update 
verify 
vary 
work with 


CL Command Abbreviations 


The following is a list of all abbreviations that are used in CL command names, 


including command verb abbreviations: 


Command Abbreviation 


A (suffix) 
ABN 
ACC 
ACCGRP 
ACG 
ACN 
ACNE 
ACT 
ADD 
ADM 


ADP 
ADPI 
ADPP 
ADPT 
ADR 
ADSM 
AFP 
AJE 
ALC 
ALR 
ALRD 
ALRTBL 
ALS 
ANS 
ANZ 
AP 
APAR 
APF 
APP 


Meaning 


attributes 

abnormal 

access code 

access group 

accounting 

action 

action entry 

active, activity, activation 

add 

application development manager, 
administration, administrative 
adopt, adopting 

adapter information 

adapter profile 

adapter 

address 

ADSTAR distributed storage manager 
advanced function printing 
autostart job entry 

allocate 

alert 

alert description 

alert table 

alias 

answer 

analyze 

access path 

authorized program analysis report 
advanced printer function 
application 
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Command Abbreviation 
APPC 


APPN® 
APY 
ARA 
ARC 
ASC 
ASK 
ASN 
ASP 
AST 
ATM 


CCT 
CCTRTE 
CCTSRV 
CDE 
CDS 
CFG 
CFGL 
CFGLE 
CGY 
CHG 
CHK 
CHT 
CICS 

CL 


Meaning 


advanced program-to-program 
communications 
advanced peer-to-peer networking 
apply 

area 

archive 

asynchronous 

ask 

association 

auxiliary storage pool 
assistance 

asynchronous transfer mode 
attention 

attribute 

audit, auditing 
authority 

authentication entry 
authorization list 

back 

balance, balancing 
BASIC language 
barcode 

batch 

backup 

backup 

business graphics utility 
breakpoint 

backup 

binding, bound 

boot protocol 

BRMS (backup recovery and media services) 
binary synchronous 

bsc file 

buffer 

C language 

calendar 

call 

capture 

COBOL language 
change control server 
IPX circuit 

circuit route 

circuit service 

code, coded 

coded data store 
configuration 
configuration list 
configuration list entry 
category 

change 

check 

chart 

customer information control system 
control language 
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Command Abbreviation Meaning 

CLD C locale description 

CLG catalog 

CLNUP cleanup 

CLO close 

CLR clear 

CLS class 

CLT client 

CMD command 

CMN communications 

CMNE communications entry 

CMNF communications file 

CMP compare 

CMT commit 

CNL cancel 

CNN connection 

CNNL connection list 

CNNLE connection list entry 

CNR container 

CNT contact 

CNV conversation 

CODE cooperative development environment 

COL collection 

COM community 

COSD class-of-service description 

CP check pending 

CPH cipher 

CPIC common programming interface for 
communications 

CPP C++ language 

CPR compress 

CPT component 

CPY copy 

CPYSCN copy screen 

CRG cluster resource group 

CRL crawler 

CRP cryptographic 

CRQ change request 

CRSDMN cross-domain 

CRT create 

CSI communications side information 

CSL console 

CST constraint, customization 

CTG cartridge 

CTL control 

CTLD controller description 

CUR current 

CVN conversion 

CVT convert 

D (suffix) description 

DAT date 

DB database 

DBF database file 

DBG debug 

DCL declare 
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Command Abbreviation Meaning 

DCP decompress 

DCT dictionary 

DDI distributed data interface 
DDM distributed data management 
DDMF distributed data management file 
DEP dependent 

DEV device 

DEVD device description 
DFN definition 

DFT default 

DFU data file utility 

DHCP dynamic host configuration protocol 
DIR directory 

DIRE directory entry 
DIRSHD directory shadow 

DKT diskette 

DKTF diskette file 

DL DataLink 

DLC deallocate 

DLF DataLink file 

DLFM DataLink file manager 
DLO document library object 
DLT delete 

DLY delay 

DMN domain 

DMP dump 

DNS domain name service 
DO do 

DOC document 

DOM Domino™ 

DPCQ DSNX/PC queue 

DPR DataPropagator™ Relational 
DSC disconnect 

DSK disk 

DSP display 

DSPF display file 

DST distribution 

DSTL distribution list 

DSTLE distribution list entry 
DSTQ distribution queue 
DSTSRV distribution services 
DTA data 

DTAARA data area 

DTAQ data queue 

DUP duplicate 

DWN down 

E (suffix) entry 

EDT edit 

EDTD edit description 

EDU education 

EJT eject 

EML emulate, emulation 
ENC encipher 

END end 
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Command Abbreviation 


ENR 
ENV 
ENVVAR 
EPM 
ERR 
ETH 
EWC 
EWL 
EXIT 
EXP 
EXT 

F (suffix) 
FAX 
FCN 
FCT 
FCTE 
FD 

FFD 

FIL 

FILL 
FLR 
FMT 
FNC 
FND 
FNT 
FNTRSC 
FNTTBL 
FORM 
FORMD 
FORMDF 
FR 

FRM 
FRW 
FIN 
FTP 

FTR 
GDF 
GEN 
GO 
GPH 
GPHPKG 
GRP 
GRT 
GSS 
HDB 
HDW 
HDWRSC 
HLD 
HLL 
HLP 
HLR 
HOST 
HST 
HTE 


Meaning 


enrollment 
environment 
environment variable 
extended program model 
error 

ethernet 

extended wireless controller 
extended wireless line 
exit 

expiration, export 
extract 

file 

facsimile 

function 

forms control table 
forms control table entry 
file description 

file field description 
file 

fill 

folder 

format 

finance 

find 

font 

font resource 

font table 

form 

form description 
form definition 
frame relay 

from 

firewall 

FORTRAN language 
file transfer protocol 
filter 

graphics data format 
generate 

go to 

graphics 

graph package 
group 

grant 

graphic symbol set 
host database 
hardware 

hardware resources 
hold, held 

high level language 
help 

holder 

host 

history, historical 
host table entry 
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Command Abbreviation 


HTTP 
I (suffix) 
ICF 
ICFF 
IDD 
IDLC 
IDX 
IDXE 
IFC 
IMG 
IMP 
INF 
INP 
INS 
INT 
INTR 
INZ 
IPI 
IPL 
IPS 
IPX 
IPXD 
ISDB 
ISDN 
ITF 
ITG 
ITM 
IWS 
JOB 
JOBD 
JOBE 
JOBQ 
JOBQE 
JRN 
JRNRCV 
JS 
JVA 
KBD 
KEY 
L (suffix) 
LAN 
LANG 
LBL 
LCK 
LCL 
LCLA 
LF 
LFM 
LIB 
LIBL 
LIBM 
LIC 
LIN 
LIND 


Meaning 


hypertext transfer protocol 
information, item, ILE 
intersystem communications function 
icf file 

interactive data definition utility 
ISDN data link control 
index 

index entry 

interface 

image 

import 

information 

input 

install 

internal machine 
intrasystem 

initialize 

internet protocol over IPX 
initial program load 
internet protocol over SNA 
internetwork packet exchange 
IPX description 

interactive source debugger 
integrated services digital network 
interactive terminal facility 
integrity 

item 

intelligent work station 

job 

job description 

job entry 

job queue 

job queue entry 

journal 

journal receiver 

job scheduler 

Java™ 

keyboard 

key 

list 

local area network 
language 

label 

lock 

local 

local attributes 

logical file 

logical file member 

library 

library list 

library member 

license, licensed 

line 

line description 
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Command Abbreviation 


LNK 
LOC 
LOCALE 
LOD 
LOF 
LOG 
LOGE 
LPD 
LPDA 
LPR 
LWS 

M (suffix) 
MAC 
MAIL 
MAP 
MAX 
MBR 
MDL 
MED 
MEDDFN 
MEDI 
MFS 
MGD 
MGR 
MGTCOL 
MLB 
MLM 
MNT 
MNU 
MOD 
MODD 
MON 
MOV 
MRG 
MSF 
MSG 
MSGD 
MSGF 
MSGO 
MST 
M36 
M36CFG 
NAM 
NCK 
NDSCTX 


Meaning 

link 

location 

locale 

load 

logical optical file 

log 

log entries 

line printer daemon 

link problem determination aid 
line printer requester 

local work station 

member 

message authentication code 
mail 

map 

maximum 

member 

model 

media 

media definition 

media information 

mounted file system 
managed 

migrate, migration, manager 
management collection 
media library 

media library media 
minutes, maintenance 

menu 

mode, module 

mode description 

monitor 

move 

merge 

mail server framework 
message 

message description 
message file 

message queue 

master 

AS/400 Advanced 36® machine 
AS/400 Advanced 36 machine configuration 
name 

nickname 

NetWare directory services context 
network 

network file 

network file system 

node group 

node list 

netbios 

NetFinity 

Notes”™ 

NetWare 
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Command Abbreviation Meaning 

NWI network interface 

NWS network server 

NWSAPP network server application 
NWSD network server description 
OBJ object 

OCL operation control language 
OF optical file 

OFC office 

OFF off 

OMC object management cycle 
OPC opticonnect 

OPN open 

OPT optical 

ORD order 

OUT out, outgoing, output 
OUTQ output queue 

OUTQD output queue description 
OVL overlay 

OVLU overlay utility 

OVR override 

OWN owner 

PAG page, paginate 

PAGDFN page definition 

PAGS page segment 

PAGSEG page segment 

PARM parameter 

PART part 

PASTHR pass through 

PC personal computer 

PCD pce document 

PCL protocol 

PCO pc organizer 

PCY policy 

PDG print descriptor group 
PDM programming development manager 
PEX performance explorer 

PF physical file 

PFD printout format definition 
PFM physical file member 

PFR performance 

PFRG performance graphics 
PFRT performance tools 

PFU print format utility 

PFX prefix 

PGM program 

PGP primary group 

PGR pager 

PHS phase 

PIN personal identification number 
PJ prestart job 

PJE prestart job entry 

PKG package 

PLI PL/I (programming language one) 
PMN permission 
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Command Abbreviation Meaning 

PMT prompt 

PNLGRP panel group 

POF physical optical file 

POL pool 

POP post office protocol 

PORT port 

POS position 

PPP point-to-point protocol 

PRB problem 

PRC procedure 

PRD product 

PREF profile 

PRFL profile list 

PRJ project 

PRM promote 

PRP preparation 

PRS personal 

PRT print 

PRTIF printer file 

PRTQ print queue 

PSFCFG print services facility configuration 

PEC portable transaction computer 

PTF program temporary fix 

PTP point-to-point 

PTR pointer 

PVD provider 

PWD password 

PWR power 

PYM payment 

QM query management 

ORY query 

ORYF query file 

OSH Qshell interpreter 

QST question 

RBD rebuild 

RCD record 

RCL reclaim 

RCV receive 

RCY recovery 

RDAR report/data archive and retrieval 

RDB relational database 

RDR reader 

REF reference 

REG registration 

REX REXX (restructured extended executor 
language) 

RGP ranking group 

RGPE ranking group entry 

RGZ reorganize 

RJE rje 

RLS release 

RLU report layout utility 

RMC report management cycle 

RMT remote 
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Command Abbreviation 


RMV 
RNM 
ROLL 
RPC 
RPDS 


SAV 
SAVF 
SAVRST 
SBM 
SBS 
SBSD 
SCD 
SCDE 
SCHIDX 
SCHIDXE 
SCN 
SDA 
SDLC 
SEC 

SET 
SEU 
SFW 
SHD 
SHRPOOL 
SIGN 
SIT 

SLT 
SLTE 
SMG 
SMW 


Meaning 


remove 
rename 

roll 

remote procedure call 
VM/MVS bridge (formerly Remote Spooling 
Communications Subsystem (RSCS)/PROFS 
distribution services) 
report program generator 
replace 

report 

reply 

reply list 

request 

reroute 

resource 

remote system information 
resume 

restore 

RouteD (TCP/IP) 

route entry 

routing entry 

retail 

retail file 

return 

retrieve 

run 

revoke 

remote work station 
REXEC (remote execution) 
save 

save file 

save and restore 

submit, submitted 
subsystem 

subsystem description 
schedule 

schedule entry 

search index 

search index entry 

screen 

screen design aid 
synchronous data link control 
security 

set 

source entry utility 
software 

shadow, shadowing 
shared pool 

sign 

situation 

select, selection 

selection entry 

system manager 

system manager workstation 
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Command Abbreviation 
MTP 


S 
=) 
S 
S 
5 
5 
S 


SPADCT 
SPL 
SPLE 
SPT 
SPIN 
SQL 
SRC 
SRCF 
SRV 
SRVPGM 
SSN 
SSND 
SST 
STC 
STG 
STGL 
STM 
STR 
STS 
SVR 
SWA 
SWL 
SYS 
SYSCTL 
SYSDIR 
SYSVAL 
S34 

S36 

$38 
TAP 
TAPF 
TBL 
TBLE 
TCP 


TDLC 
TELN 
TFR 
TFTP 
THD 
THLD 
TIE 
TIEF 
TNS 
TO 
TOS 


Meaning 


simple mail transfer protocol 
systems network architecture 
send 

SNA over IPX 

simple network management protocol 
SNA pass through 

SNA upline facility 

sphere of control 

spelling aid dictionary 
spooling 

spooled file 

support 

support network 
structured query language 
source 

source file 

service 

service program 

session 

session description 

system service tools 
statistics 

storage 

storage link 

stream, statement 

start 

status 

server 

save while active 

stop word list 

system 

system control 

system directory 

system value 

System /34 

System/36 

System/38 

tape 

tape file 

table 

table entry 

TCP/IP (transmission control 
protocol/internet protocol) 
twinaxial data link control 
telnet 

transfer 

trivial file transfer protocol 
thread 

threshold 

technical information exchange 
tie file 

transaction 

to 

type of service 
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Command Abbreviation Meaning 

TPL template 

TRC trace 

TRG trigger 

TRN token-ring network 
TRP trap 

TXT text 

TYPE type 

T1 transport class 1 

UBC Ultimedia business conference 
UDFS user-defined file system 
UPD update 

UPG upgrade 

USF Ultimedia system facilities 
USG usage 

USR user 

USRIDX user index 

USRPRF user profile 

USRPRTI user print information 
USRQ user queue 

USRSPC user space 

VAL value 

VAR variable 

VFY verify 

VLDL validation list 

VOL volume 

VRY vary 

VT VT100 or VT220 

VWs virtual work station 
WAIT wait 

WLS wireless 

WNT Windows NT® 

WP word processing 
WRK work with 

WSE work station entry 
WSG workstation gateway 
WSO workstation object 
WTR writer 

X25 X.25 


CL Command Keyword Abbreviations 


Each command parameter has a keyword name associated with it. The keyword 
name can be up to ten characters. Keyword names do not follow the same style as 
command names in that they do not necessarily begin with a command verb. 
Where possible, use a single word or abbreviation. For example, common keyword 
names in CL commands include OBJ (Object), LIB (Library), TYPE, OPTION, TEXT, 
and AUT (Authority). 


Construct a keyword name whenever using more than a single word or 
abbreviation to describe the parameter. Construct the keyword name by using a 
combination of standard command abbreviations and short unabbreviated words. 
For example, OBJTYPE is a common keyword name which combines the 
abbreviation ‘OBJ’ with the short word ’TYPE’. 
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Abbreviations of CL Commands and Keywords 


The two primary goals for keyword names are to be recognizable and to be 
consistent between commands that provide the same function. Use of simple 
words and standard abbreviations helps to make the keyword names recognizable. 


The following is a list of abbreviations that are used in CL command parameter 


keyword names: 


A (suffix) 
ABS 

ABN 

AC 

ACC 
ACCMTH 
ACG 

ACK 
ACN 

ACP 

ACQ 
ACSE 
ACT 
ACTSNBU 
ADDR (or ADR) 
ADJ 

ADL 
ADM 


ADMD 
ADP 
ADPT 
ADR (or ADDR) 
ADV 
AIX® 
AJE 
AFP 
ALC 
ALM 
ALR 
ALRD 
ALS 
ALW 
ANET 
ANS 
ANZ 
AP 
APAR 
APE 
APPP 
APW 
APP 
APPC 


APPN 
APY 
ARA 
ARP 


Keyword Abbreviation 


Meaning 


attributes, activity, address 
abstract, absolute 

abnormal 

autocall 

access, access code 

access method 

accounting 

acknowledge, acknowledgement 
action 

accept 

acquire 

association control service element 
active, activate, activation, activity, action 
activate switched network backup 
address 

adjacent, adjust 

additional 

administration, Application Development 
Manager 

administration domain 

adopt, adaptive 

adapter 

address 

advance 

AIX operating system 

autostart job entry 

advanced function printing 
allocate 

alarm 

alert 

alert description 

alias 

allow 

adjacent network entity title 
answer 

analyze 

access path 

authorized program analysis report 
advanced printer function 
application process 

advanced print writer 

application 

advanced program-to-program 
communications 

advanced peer-to-peer networking 
apply 

area 

address resolution protocol 
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ASC 
ASCII 


ASMT 
ASN 

ASP 

AST 

ASYNC 

ATD 

ATN (or ATTN) 
ATR (or ATTR) 
ATTACH 
ATTN (or ATN) 
ATTR (or ATR) 
AUD 

AUT 

AUTL 

AUTO 

AUX 

AVG 

AVL 

BAL 

BAS 

BCD 

BCH 

BCKLT 
BCKUP (or BKU) 
BDY 

BEX 

BGU 

BIN 

BIO 

BITS 

BKP 

BKT 

BKU (or BCKUP) 
BLDG 

BLK 

BLN 

BND 

BNR 

BOT 

BRK 

BSC 

BSCEL 


Keyword Abbreviation 


Meaning 


asynchronous communications 
American National Standard Code for 
Information Interchange 
assignment 

assigned, association 
auxiliary storage pool 
assistance 

asynchronous 

attended 

attention 

attribute 

attached 

attention key 

attribute 

audit, auditing 
authority, authorized, authorization 
authorization list 
automatic 

auxiliary 

average 

available 

balance 

BASIC language, base 
barcode, broadcast data 
batch 

backlight 

backup 

boundary 

branch extender 
business graphics utility 
binary 

block input/output 

data bits 

breakpoint 

bracket, backout 
backup 

building 

block 

blinking cursor 

binding, bind, bound 
banner 

bottom 

break 

binary synchronous communications 
binary synchronous communications 
equivalence link 
backspace 

buffer 

C language 

cabinet 

calendar 

capacity, capture 
callback 

COBOL language 
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CCD 

CCSID 

CCT 

CDE 

CDR 

CFG 

CFGL 

CFGLE 

CFM 

CGU 

CHAR (or CHR) 
CHG 

CHK 

CHKSUM 
CHKVOL 

CHL 

CHR (or CHAR) 
CHRSTR 

CHT 

CGY 

CKR 

CKS 

CL 

CLG 

CLN 

CLNS 

CLNUP (or CLN) 
CLO 


Meaning 


call control data 

coded character set identifier 
circuit 

code 

call detail records 
configuration 
configuration list 
configuration list entry 
confirmation, confirm 
character generator utility 
character 

change 

check 

checksum 

check volume identifier 
channel 

character 

character string 

chart 

category 

checker 

checksum 

control language 
catalog 

clean, cleaning, cleanup 
connectionless-mode network service 
cleanup 

close 

clear 

class 

class file 

client 

cluster 

command 
communications 
communications entry 
compare 

commitment, comment 
congestion 

cancel 

connection limit 
connection 

connection list 
connection limit 
container 

constant 

contact 

control 

country 

conversation 

code 

code page 

code, cooperative development environment 
column, collection 
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COM common, community 
COMPACT compact, compaction 
CON confidential 

CONCAT concatenation 

COND condition 

CONS connection-mode network service 
CONTIG contiguous 

CONT continue 

COS class-of-service 

COSD class-of-service description 
COSTBYTE cost per byte 

COSTCNN cost per connection 
COVER cover letter 

CP control point 

CPB change profile branch, compatibility 
CPI characters per inch 

CPL complete 

CPP C++ language 

CPR compressed, compress 
CPS call progress signal 

CPT component 

CPU central processing unit 
CPY copy 

CPYRGT copyright 

CRC cyclic redundancy check 
CRDN credentials 

CRG charges, charging, cluster resource group 
CRL correlation 

CRQ change request 

CRQD change request description 
CRSDMNK cross-domain key 

CRT create 

CSI communications side information 
CSL console 

CSR cursor 

CST constraint, cost 

CTG cartridge 

CTL controller, control 

CTLD controller description 
CTN contention 

CTS clear to send 

CTX context 

CUR current 

CVN conversion 

CVR cover 

CVT convert, converting 

CXT (or CTX) context 

CYC cycle 

D (suffix) description 

DAP directory access protocol 
DAT date 

DB database 

DBCS double-byte character set 
DBF database file 


426 0S/400 CL Programming V5R2 


Abbreviations of CL Commands and Keywords 


Keyword Abbreviation 


DBG 
DBR 
DCE 


DCL 
DCP 
DCT 
DDI 
DDM 
DDMF 
DDS 
DEC 
DEGREE 
DEL 
DEP 
DEPT 
DES 
DEST 
DEV 
DEVD 
DEN 
DFR 
DFT 
DFU 
DIAG 
DIF 
DIFF 
DIR 
DKT 
DLC 
DLO 
DLT 
DLVRY 
DLY 
DMN 
DMP 
DN 
DOC 
DPR 
DRAWER 
DRT 
DRV 
DSA 
DSAP 
DSB 
DSC 
DSK 
DSP 
DST 
DTA 
DTE 
DTL 
DUP 
DVL 


Meaning 


debug 

database relations 

data communications equipment, distributed 
computing environment 
declare 

decompress 

dictionary 

distributed data interface 
distributed data management 
distributed data management file 
data description specification 
decimal 

parallel processing degree 
delivery 

dependent 

department 

data encryption standard 
destination 

device 

device description 

definition, defined 

defer 

default 

data file utility 

dialogue 

differences 

differentiated 

directory 

diskette 

deallocate 

document library object 
delete 

delivery 

delay 

domain 

dump 

distinguished name 
document 

DataPropagator Relational 
drawers 

direct 

drive 

directory systems agent 
destination service access point 
disable, disabled 

disconnect 

disk 

display 

dedicated service tools, distribution 
data 

data terminal equipment 
detail 

duplicate 

development 
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DWN down 

E (suffix) entry 

EBCDIC extended binary-coded decimal interchange 
code 

EDT edit 

EDU education 

EJT eject 

ELAN ethernet LAN 

ELEM element 

ELY early 

EML emulate, emulation 

ENB enable 

ENC encode 

ENR enrollment 

ENT enter 

ENV environment 

EOF end of file 

EOR end of record 

EOV end of volume 

ERR error 

EST establish, established 

ETH ethernet 

EVT event 

EXC exclude 

EXCH exchange 

EXD extend, extended 

EXEC executive 

EXIST existence 

EXN extension 

EXP expiration, expire 

EXPR expression 

EXT extract, extend, extended 

F (suffix) file 

Fnn function key ‘nn’ 

FA file attributes 

FAX facsimile 

FCL facilities 

FCN functional 

FCT forms control table 

FCTE forms control table entry 

FEA front end application 

FEA front end application 

FEAT feature 

FIL file 

FLD field 

FLG flag 

FLIB files library 

FLR folder 

FLW flow 

FMA font management aid 

FMT format 

FNC finance 

FNT font 

FORMDF form definition 
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Keyword Abbreviation 


FP 
FRAC 
FRC 
FRI 
FRM 
FRQ 
FSC 
FSN 
FST 
FTAM 
FTP 
FTR 
GC 
GCH 
GDF 
GDL 
GEN 
GID 
GIV 
GLB 
GNL 
GPH 
GRP 
GRT 
GSS 
GVUP 
HCP 
HDL (or HNDL) 
HDR 
HDW 
HEX 
HFS 
HLD 
HLL 
HLP 
HLR 
HNDL (or HDL) 
HPCP 
HPFCS 
HPR 
HRZ 
HST 
HTML 
HTTP 
I (suffix) 
ICF 
ICV 
ID 
IDD 
IDL 
IDLC 
IDP 
IDX 
IE 


Meaning 


focal point 

fraction 

force 

Friday 

from, frame 

frequency 

fiscal 

file sequence number 

first 

file transfer, access, and management 
file transfer protocol (TCP/IP) 
filter 

garbage collection 

garbage collection heap 
graphics data file 

guideline, guidelines 
generate, generation 

group identifier number 

give 

global 

general 

graph 

group 

grant 

graphics symbol set 

give up 

host command processor 
handle 

header 

hardware 

hexadecimal 

hierarchical file systems 
hold, held 

high-level language 

help 

holder 

handle 

host to printer code page 
host to printer font character set 
high performance routing 
horizontal 

history, historical 

hypertext markup language 
hypertext transfer protocol (TCP/IP) 
information, ILE 

intersystem communication function 
initial chaining value 
identifier 

interactive data definition 
idle 

integrated data link control 
interchange document profile 
index 

information element 
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IFC 
IGC 
IGN 
IFC 
ILE 
IMG 


INP 


INQ 
INS 
INST 

NT 
NTNET 
NTNETA 


I 
I 
I 
I 
I 
I 


I 
IPDS™ 
IPI 

IPL 

IPX 

ISDN 

IT 

ITF 

ITM 

ITV 

IW2 

J (suffix) 
JDFT 

JE (suffix) 
JFLD 
JORDER 
JRN 
JRNRCV 
JVA 

KBD 


KWD 

L (suffix) 
LADN 
LAN 


Keyword Abbreviation 


AC (or INACT) 
ACT (or INAC) 


INPACING 


Meaning 


interface 

ideographic (double-byte character set) 
ignore 

interface 

integrated language environment 
image 

input 

inactivity 

inactivity 

include 

indirect 

information 

Infoseeker 

inhibit 

initiate 

initial 

intermediate 

input 

inbound pacing 

inquiry 

install 

instance 

interactive, integer, internal 
internet 

internet address 

intrasystem 

invitee, inventory, invoke 
initialize, initialization 
internet protocol 

intelligent printer data stream 
IP over IPX 

initial program load 

internet packet exchange 
integrated services digital network 
intermediate text, internal text 
interactive terminal facility 
item 

interval 

IPX WAN version 2 protocol 
job 

join default 

job entry 

join field 

join file order 

journal 

journal receiver 

Java 

keyboard 

know, knowledge 

Kanji printer function 
keyword 

list 

library assigned document name 
local area network 
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Keyword Abbreviation Meaning 

LANG (or LNG) language 

LBL label 

LCL local 

LCLE local location entry 
LCK lock 

LDTIME lead time 

LE (suffix) list entry 

LEC LAN emulation client 
LECS LAN emulation configuration server 
LEN length 

LES LAN emulation server 
LF logical file 

LFM logical file member 
LFT left 

LGL logical 

LIB library 

LIBL library list 

LIC licensed, license 
LIFTM lifetime 

LIN line, line description 
LMI local management interface 
LMT limit 

LNG (or LANG) language 

LNK link 

LNR listener 

LOC location 

LOD load 

LPI lines per inch 

LRC longitudinal redundancy check 
LRSP local response 

LST list, last 

LTR letter 

LVL level 

LWS local work station 
LZYWRT lazy write 

M (suffix) member, messages 
MAC macro, medium access control 
MAINT maintenance 

MAJ major 

MAP map, manufacturing automation protocol 
MAX maximum 

MBR member 

MBRS members 

MCA message channel agent 
MCH machine 

MDL model 

MDM modem 

MDTA message data 

MED media, medium 

MEDI media information 
METAFILE metatable file 

MFR manufacturer 

MFS mounted file system 
MGR manager 
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MGRR manager registration 

MGT management 

MID middle 

MIN minimal, minimize 

MLB media library device 

MLT multiplier, multiple 

MM multimedia 

MNG manage 

MNT maintenance, mount, mounted 
MNU menu 

MOD mode, module 

MODD mode description 

MON monitor, Monday 

MOV move 

MOM Message Queue Manager 
MRG merge 

MRK mark 

MRT multiple requester terminal 
MSF mail server framework 
MSG message 

MSGS messages 

MSGQ message queue 

MSR measurement 

MSS managed system services 
MST master 

MTD mounted 

MTG meeting 

MTU maximum transmission unit 
MTH method 

MULT (or MLT) multiple 

M36 AS/400 Advanced 36 machine 
M36CFG AS/400 Advanced 36 machine configuration 
N (suffix) name, network 

NAM name 

NBR number 

NCK nickname 

NDE node 

NDM normal disconnect mode 
NDS NetWare directory services 
NEG negative, negotiation 

NEP never-ending program 

NET network 

NFY notify 

NL network-layer 

NLSP NetWare link services protocol 
NML namelist 

NNAM (or NCK) nickname 

NOD node 

NODL node list 

NORM normal 

NOTVLD not valid 

NPRD nonproductive 

NRM normal, normal response mode 
NRZI non-return-to-zero-inverted 
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Keyword Abbreviation 


ORG 
ORGUNIT 
OS 
OSDB 
OUT 
OVF 
OVL 
OVR 
OVRFLW 
OWN 
PAD 
PAG 
PARM 
PASTHR 
PBL 

PBX 

PC 

PCD 
PCL 
PCO 
PCS 
PCT 
PCTA 
PCY 
PDG 
PDM 
PDU 
PENWTH 
PERS 

PF 

PFnn 


Meaning 


network termination 
NetBIOS 

NetBIOS description 
notice 

NetFinity 

Notes 

NetWare 

NetWare 3.12 

numeric, number 

network interface 

network interface description 
network server 

network server description 
next 

object 

observable information 
office 

offset 

omit 

open 

operator, operating 

option, optical, optimum 
order 

organization, organizational 


organizational unit 
operating system 

object store database 

output 

overflow 

overlay 

override 

overflow 

owner, owned 

packet assembly /disassembly 
page, paginate 

parameter 

pass-through 

probable 

private branch exchange 
personal computer 

PC document 

protocol 

PC organizer 

personal computer support 
percent 

personal computer text assist 
policy 

print descriptor group 
programming development manager 
protocol data unit 

pen width 

personal 

physical file 

program function key ‘nn’ 
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Keyword Abbreviation 


PFD 
PFM 
PFVLM 
PFR 
PFX 
PGM 
PGP 
PGR 
PHCP 
PHFCS 
PHS 
PHY 
PIN 
PIE 
PKA 
PKG 
PKT 

PL 

PLC 
PLL 
PLT 
PMN 
PMP 
PMT 
PND 
PNL 
PNT 
POL 
POLL 
POP 
PORT 
POS 
PPP 
PPR 
PPW 
PRB 
PRC 
PRD 
PRJ 
PREBLT 
PRED 
PREEST 
PREF 
PREOPR 
PREREQ 
PRF 
PRI 

PRJ 
PRM 
PRMD 
PRN 
PRO 
PROC (or PRC) 
PROD 


Meaning 


printout format definition 
physical file member 
physical file variable-length member 
performance 

prefix 

program 

primary group 

pager 

printer to host code page 
printer to host font character set 
phase 

physical 

personal identification number 
prestart job entry 

public key algorithm 
package 

packet 

presentation-layer 

place 

poll, polling 

plotter 

permission 
point-to-multipoint 

prompt 

pending 

panel 

point 

pool 

polled, polling 

post office protocol (TCP/IP) 
port number 

positive, position 
point-to-point protocol 
paper 

page printer writer 

problem 

procedure, procedural, process 
product, productive 

project 

prebuilt 

predecessor 

pre-established 

preferred 

pre-operation 

prerequisite 

profile, profiling 

primary 

project 

promote, parameters 

private management domain 
parent 

proposed 

procedure, processing 
production 
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PROP property /properties 

PRP prepare, propagate, propagation 

PRS personal 

PRT print, printer 

PRTQ print queue 

PRV previous 

PRX proxy 

PSAP presentation-layer service access point 

PSF print services facility 

PSN presentation 

PSTOPR post-operation 

PTC protected, protection, portable transaction 
computer 

PTF program temporary fix 

PTH path 

PTN partition, partitioning 

PTP point-to-point 

PTR pointer 

PTY priority 

PUB public 

PUNS punches 

PVC permanent virtual circuit 

PVT private 

PWD password 

PWR power 

Q (suffix) queue 

QE (suffix) queue entry 

OLTY quality 

ORY query 

QST question 

QSTDB question-and-answer database 

OSTLOD question-and-answer load 

QUAL qualifier 

RAR route addition resistance 

RBD rebuild 

RCD record 

RCDS records 

RCL reclaim 

RCMS remote change management server 

RCP recipient 

RCR recursion, recurs 

RCV receive 

RCY recovery 

RDB relational database 

RDN relative distinguished name 

RDR reader 

RDRE reader entry 

REACT reactivation 

REASSM reassembly 

REC record 

RECNN reconnect 

REF reference 

REINZ reinitialize 

REL relations, release 
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REP 
REQ (or RQS) 
RES 
RESYNC 
RET 
REX 

RFS 

RGS 
RGT 
RGZ 
RINZ 
RIP 

RJE 

RLS 


ROS (or REQ) 
ROT 
RRSP 


Keyword Abbreviation 


Meaning 


representation 
required, request, requester 
resident, resolution 
resynchronize 
retention 

REXX language 
refuse, refused 
registration 

right 

reorganize 
reinitialize 

routing information protocol 
remote job entry 
release 

remind, reminder 
remote 

remove 

range 

rename 

RPG language 
replace, replacement 
report 

reply 

request, requester 
requisite 

remote response 
reroute 

resource, resources 
result, resolution 
resume 

response 

resource 

restore 

restricted 

route 

routing 

retail 

return, returned, retransmission 
router 

rotate 

retrieve 

retry 

request unit 

revoke 

reverse 

remote work station 
systems application architecture 
saddle 

service access point 
Saturday 

save 

save file 

submit, submitted 
subsystem 
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Keyword Abbreviation 


SCD 

SCH 

SCN 

SCT 

SDLC 
SDU 

SEC 

SEG 
SEGMENT 
SEL (or SLT) 
SENSITIV 
SEP 

SEQ 

SEV 

SFW 

SGN 

SHD 

SHF 

SHM 

SHR 

SI 

SIG 

SIGN 

SIZ 

SL 

SLR 

SLT (or SEL) 


= 
> 
esl 


NNNnNANNANANHNNNWNN 


SPT 
SPIN 

SPX 

SQL 

SRC 

SRCH (or SCH) 


Meaning 


schedule, scheduled 
search 

screen 

sector 

synchronous data link control 
service data unit 

second, security 

segment 

segmentation 

select, selection 

sensitivity 

separator 

sequence, sequential 
severity 

software 

sign-on 

shadow, shadowing 

shift 

short hold mode 

shared 

shift-in 

signature, signed 

sign-on 

size 

session-layer 

selector 

select, selection 

systems management application entity 
systems manager 

simple mail transfer protocol 
summary 

systems network architecture 
switched network back-up 
send 

single 

SNA over IPX 

snap 

SNA pass-through 

SNA upline facility 
shift-out 

sphere of control 

spelling aid 

space, special 

supplied 

specific 

service provider identifier 
spooled, spooling 
superseded 

support, supported 
support network 
sequenced packet exchange 
structured query language 
source 

search 
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SRM 
SRQ 
SRT 
SRV 
SSAP 


SSCP 
SSL 

SSN 
SSND 
SSP 

SST 
STAT 
STATION 
STC 

STD 
STG 

STK 
STM 
STMF 
STMT 
STN 

STP 
STPL 
STR 

SIS 

STT 

STX 

SUB 
SUBADR 
SUBALC 
SUBDIR 
SUBFLR 
SUBNET 
SUBPGM 
SUBST 
SUCC 
SUN 
SURNAM 
SVC 
SVR 
SWL 
SWS 
SWT 
SWTSET 
SYM 
SYN 
SYNC 
SYS 
SYSLIBL 
S36 

TAP 
TAPDEV 
TBL 


Keyword Abbreviation 


Meaning 


system resource management 
system request 

sort 

service 


source service access point, session-layer 


service access point 
system services control point 
secure sockets layer 
session 

session description 
suspend 

system service tools 
statistical data records 
convenience station 
statistics 

standard 

storage 

stack 

stream 

stream file 
statement 

station 

step 

staple 

start, starting 

status 

state 

start-of-text character 
substitution, subject 
subaddress 
suballocation 
subdirectory 
subfolder 
subnetwork 
subprogram 
substitution 
successor 

Sunday 

surname 

switched virtual circuit 
server 

stop word list 
switches 

switch, switched 
switch setting 
symbol, symbolic 
syntax 

synchronous 
system 

system library list 
System/36 

tape 

tape devices 

table 
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TCID 
TCP 


TCS 
TDC 
TDLC 
TEID 
TEL 
TELN 
TERM 
TER 
TGT 
THD 
THLD 
THR 
THRPUT 
THS 
THU 
TIE 
TIM 
TIMMRK 
TIMO 
TIMOUT (or TIMO) 
TKN 
TL 
™ 
TMN 

TMP 

TMR 

TMS 

TMT 

TNS 

TOKN (or TKN) 
TOT 

TPDU 

TPL 

TPT 

TRANS 

TRC 

TRG 

TRM 

TRN 

TRNSPY 

TRP 

TRS 

TRUNC 

TSE 

TSP 

TSAP 

TST 

TUE 

TWR 

TXP 

TXT 


Meaning 


transport connection identifier 
TCP/IP (transmission control 
protocol/internet protocol) 
telephony connection services 
telephony data collector 
twinaxial data link control 
terminal endpoint identifier 
telephone 

TELNET (TCP/IP) 

terminal 

transfer 

target 

thread 

threshold 

through, throughput 
throughput 

thesaurus 

Thursday 

technical information exchange 
time 

timemark 

timeout 

timeout 

token 

transport-layer 

time 

transmission 

temporary 

timer 

transmission 

transmit 

transaction 

token 

total 

transport-layer protocol data unit 
template, topology 

transport 

transit, transaction 

trace 

trigger 

term 

token-ring network, translate 
transparency 

trap 

transit 

truncate 

timeslice end 

timestamp 

transport-layer service access point 
test 

Tuesday 

tower 

transport 

text 
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TYP type 

T1 transport class 1 

T2 transport class 2 

T4 transport class 4 

UDFS user-defined file system 
UDP user datagram protocol 
UI user interface, unnumbered information 
UID user identifier number 
UNC unclassified 

UNPRT unprintable 

UNQ unique 

UOM unit of measure 

UPCE universal product code type E barcode 
UPD update 

UPG upgrade 

URL uniform resource locator 
USG usage 

USR user 

VAL value 

VAR variable 

VCT virtual circuit 

VDSK virtual disk 

VER (or VSN) version 

VFY verify 

VLD valid, validity, validation 
VND vendor 

VOL volume 

VRE verification 

VRT virtual 

VRY vary 

VSN (or VER) version 

VWS virtual work station 
WAN wide area network 
WDW window 

WED Wednesday 

WIN winner 

WK week 

WNT Windows NT 

WP word processing 

WRD word 

WRK work, working 

WRT write 

WS workstation 

WSC workstation controller 
WSCST workstation customization object 
WSE workstation entry 

WSG workstation gateway (TCP/IP) 
WSO workstation object 

WTR writer 

WTRE writer entry 

WTRS writers 

X25 X.25 

X31 X.31 

X400 X.400 
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Keyword Abbreviation 
3270 


Meaning 


3270 display 
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Appendix E. Notices 


This information was developed for products and services offered in the U.S.A. 
IBM may not offer the products, services, or features discussed in this document in 
other countries. Consult your local IBM representative for information on the 
products and services currently available in your area. Any reference to an IBM 
product, program, or service is not intended to state or imply that only that IBM 
product, program, or service may be used. Any functionally equivalent product, 
program, or service that does not infringe any IBM intellectual property right may 
be used instead. However, it is the user’s responsibility to evaluate and verify the 
operation of any non-IBM product, program, or service. 


IBM may have patents or pending patent applications covering subject matter 
described in this document. The furnishing of this document does not give you 
any license to these patents. You can send license inquiries, in writing, to: 


IBM Director of Licensing 
IBM Corporation 

500 Columbus Avenue 
Thornwood, NY 10594. 
U.S.A. 


For license inquiries regarding double-byte (DBCS) information, contact the IBM 
Intellectual Property Department in your country or send inquiries, in writing, to: 


IBM World Trade Asia Corporation 
Licensing 

2-31 Roppongi 3-chome, Minato-ku 
Tokyo 106-0032, Japan 


The following paragraph does not apply to the United Kingdom or any other 
country where such provisions are inconsistent with local law: 
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS 
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER 
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS 
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or 
implied warranties in certain transactions, therefore, this statement may not apply 
to you. 


This information could include technical inaccuracies or typographical errors. 
Changes are periodically made to the information herein; these changes will be 
incorporated in new editions of the publication. IBM may make improvements 
and/or changes in the product(s) and/or the program(s) described in this 
publication at any time without notice. 


Any references in this information to non-IBM Web sites are provided for 
convenience only and do not in any manner serve as an endorsement of those Web 
sites. The materials at those Web sites are not part of the materials for this IBM 
product and use of those Web sites is at your own risk. 


Licensees of this program who wish to have information about it for the purpose 
of enabling: (i) the exchange of information between independently created 
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programs and other programs (including this one) and (ii) the mutual use of the 
information which has been exchanged, should contact: 


IBM Corporation 

Software Interoperability Coordinator 
3605 Highway 52 N 

Rochester, MN 55901-7829 

Las 


Such information may be available, subject to appropriate terms and conditions, 
including in some cases, payment of a fee. 


The licensed program described in this information and all licensed material 
available for it are provided by IBM under terms of the IBM Customer Agreement, 
IBM International Program License Agreement, or any equivalent agreement 
between us. 


This information contains examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 


COPYRIGHT LICENSE: 


This information contains sample application programs in source language, which 
illustrate programming techniques on various operating platforms. You may copy, 
modify, and distribute these sample programs in any form without payment to 
IBM, for the purposes of developing, using, marketing or distributing application 
programs conforming to the application programming interface for the operating 
platform for which the sample programs are written. These examples have not 
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or 
imply reliability, serviceability, or function of these programs. You may copy, 
modify, and distribute these sample programs in any form without payment to 
IBM for the purposes of developing, using, marketing, or distributing application 
programs conforming to IBM’s application programming interfaces. 


Each copy or any portion of these sample programs or any derivative work, must 
include a copyright notice as follows: 


© (your company name) (year). Portions of this code are derived from IBM Corp. 
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights 
reserved. 


If you are viewing this information softcopy, the photographs and color 
illustrations may not appear. 


Programming Interface Information 


This publication is intended to help you to program with CL. This publication 
documents General-Use Programming Interface and Associated Guidance 
Information provided by OS/400. 


General-Use programming interfaces allow the customer to write programs that 
obtain the services of the OS/400 licensed program. 
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Trademarks 


The following terms are trademarks of International Business Machines 
Corporation in the United States, other countries, or both: 


ADSTAR 

Advanced 36 

AFP 

AIX 

APL2 

Application System /400 
APPN 

AS/400 

CallPath 

CICS 

CICS/400 

Client Access 

COBOL /400 

C/400 

DataPropagator 

DB2 

e (logo) 

IBM 

Integrated Language Environment 
IPDS 

iSeries 

MOSeries 

Language Environment 
Operating System /2 
Operating System /400 
OS/2 


System View 
System /36 
System /38 
VisualGen 
Visuallnfo 
400 


Domino, Notes, and Lotus are trademarks of Lotus Development Corporation in 
the United States, other countries, or both. 


Java and all Java-based trademarks and logos are trademarks or registered 
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. 


Microsoft, Windows, Windows NT, and the Windows logo are trademarks of 
Microsoft Corporation in the United States, other countries, or both. 


Other company, product, and service names may be trademarks or service marks 
of others. 
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Bibliography 


The following is a list of the additional books and 
a description of the information in each book. 


For information about operating the iSeries server 
and its display stations, see: 


The Getting Started with iSeries topic in the 
System Overview, Planning, and Installation 
category of the iSeries Information Center 
provides general information about how to run 
the system, how to send and receive messages 
and use the display station function keys. 


For more information about OS/400 
programming, see: 


This guide provides information about using 
DDS to create and maintain displays, creating 
and working with display files, creating online 
help information, using UIM to define displays, 
and using panel groups, records, and 
documents. 


This guide provides information about the 


different media available to save and protect 
system data. 


[LE Concept 


This book explains concepts and terminology 
pertaining to the Integrated Language 
Environment (ILE) architecture of the OS/400 
licensed program. Topics covered include 
creating modules, binding, running programs, 
debugging programs, and handling exceptions. 


The Globalization topic in the System overview, 
planning, and installation category of the 
iSeries Information Center provides the data 
processing manager, system operator and 
manager, application programmer, end user, 
IBM marketing representative, and system 
engineer with information required to 
understand and use the globalization function 
on the iSeries server. This book prepares the 
user for planning, installing, configuring, and 
using globalization and multilingual support of 
the iSeries server. It also provides an 
explanation of the database management of 
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multilingual data and application 
considerations for a multilingual system. 


This guide provides specific information on 
printing elements and concepts of the iSeries 
server, printer file and print spooling support, 
and printer connectivity. 


This book discusses general security concepts 


and planning for security on the system. It also 
includes information for all users about 


resource security. 


develop and support programs that use tape 
and diskette drives for I/O. This includes 
information on device files and descriptions for 
tape and diskette devices, as well as spooling 
for diskette devices. 


* The Systems Management category of 
information in the iSeries Information Center 
provides information about creating and 
changing the work management environment, 
working with system values, collecting and 
using performance data to improve system 
performance. 


For detailed information about API’s, see: 


* The Programming category of information in 
the iSeries Information Center 


The APIs topic provides information for 
experienced application and system 
programmers who want to use the OS/400 
application programming interfaces (APIs). This 
book provides getting started examples to help 
the programmer use APIs. 


For more information about OS/400 utilities 
mentioned in this book, see: 


This guide provides information about using 
the character generator utility (CGU) to create 
and maintain a double-byte character set on the 
iSeries server. 
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This book provides information about using the 
programming development manager (PDM) to 
work with lists of libraries, objects, members, 
and user-defined options. 


For more information about a RPG Multimedia 
Tutorial, see: 


* Experience RPG IV Tutorial 


This is an interactive self-study program 
explaining the differences between RPG III and 
RPG IV and how to work within the new ILE 
environment. An accompanying workbook 
provides additional exercises and doubles as a 
reference upon completion of the tutorial. ILE 
RPG/400 code examples are shipped with the 
tutorial and run directly on the AS/400. Dial 
1-800-IBM-CALL to order the tutorial. 
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Index 


Special Characters 


/* (comment) delimiter 30 
* (asterisk) 
comments in programs 30 
OUTPUT (output) parameter 115 
*ALL authority 110 
*AND operator 37 
*CHANGE authority 110 
*EXCL (exclusive) lock state 138 
*EXCLRD (exclusive allow read) lock 
state 138 
*EXCLUDE authority 110 
*INT2 value 339 
*INT4 value 339 
*LDA value 
local 90 
*NOT operator 37 
*OR operator 37 
*SHRNUP (shared-no-update) lock 
state 138 
*SHRRD (shared-for-read) lock state 138 
*SHRUPD (shared-for-update) lock 
state 138 
*UINT2 339 
*UINT4 339 
*USE authority 110 
%BIN (binary) function 41 
%BINARY (binary) built-in function 
description 41 
%SST (substring) function 
description 43 
processing qualified name 313 
%SUBSTRING (substring) built-in 
function 
description 43 
processing qualified name 313 
%SWITCH (switch) function 45 


A 


abnormal job end 177 
activation program 372 
add authority 110 
Add Breakpoint (ADDBKP) command 
description 374 
example 375 
Add Library List Entry (ADDLIBLE) 
command 105 
Add Message Description (ADDMSGD) 
command 
example 194 
filename 185 
FMT (format) parameter 188 
specifying information 181 
Add Program (ADDPGM) 
command 370 
Add Trace (ADDTRC) command 379 
example 379 
ADDBKP (Add Breakpoint) command 
description 374 
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ADDBKP (Add Breakpoint) command 
(continued) 
example 375 
adding 
adding to program 378 
breakpoint to program 374 
library list entry 105 
message description 
ADDMSGD (Add Message 
Description) command 194 
example 194 
file 185 
FMT (format) parameter 188 
value 181 
program objects to debug 
session 351 
trace to program 378 
ADDLIBLE (Add Library List Entry) 
command 105 
ADDMSGD (Add Message Description) 
command 
example 194 
filename 185 
FMT (format) parameter 188 
specifying information 181 
ADDPGM (Add Program) 
command 370 
ADDTRC (Add Trace) command 379 
example 379 
alert identifier 
specifying 194 
allocating 
resource 138 
Allow alerts 
alerts 
using allow alerts 201 
ALROPT code 
entry size 184 
specifying 194 
API (application programming interface) 
days used count 128 
application programming interface (API) 
days used count 128 
asterisk (*) 
comments in programs 30 
OUTPUT (output) parameter 115 
attribute 
basic 117 
command 327 
default for newly created object 113 
displaying module 60 
displaying program 60 
full 117 
message queue 200 
object description 117 
retrieving 178 
service 117 
authority 
*ALL 110 
*CHANGE 110 
*EXCLUDE 110 


authority (continued) 
*USE 110 
add 110 
combined 110 
data 110 
default for newly created object 111 
defined command 286 
delete 110 
execute 110 
library 106, 109 
object 109 
object existence 109 
object management 109 
object operational 109 
read 110 
update 110 
automatic decompression 136 
automatic variable 
program 383 


batch entry 13 
batch job 
breakpoint program 375 
debugging job not started from job 
queue 385 
submitted to a job queue, 
debugging 384 
batch job log 
consideration 275 
binary function 41 
branching 
unconditional 30 
break delivery of message 200 
break message 
sending 181, 207 
break-handling program 203, 242, 243 
breakpoint 
characteristics 356 
conditional 
add 377 
description 356 
example 360 
removing 358 


setting 358 
function 356 
removing 


conditional 358 
description 361 
from program 356 
unconditional 357 
resuming program processing 375 
setting 
conditional 358 
description 356 
unconditional 357 
unconditional 
description 356 
removing 357 
setting 357 
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breakpoint program 
batch job 375 
built-in function 14 


Cc 


calculation 17 
See alsoexpression 
CHGVAR (Change Variable) 
command 14 
call 
description 371 
level 
description 371 
nesting 371 
stack 371 
CALL (Call Program) command 
description 65 
function 17 
using 71 
Call Procedure (CALLPRC) command 
description 66 
Call Program (CALL) command 
description 65 
function 17 
using 71 
call stack 
description 371 
displaying testing information 382 
entry identification 
on SNDPGMMSG 214 
relationship to CALL command 66 
relationship to CALLPRC 
command 67 
removing call 66, 67 
removing request in error 373 
TFRCTL (Transfer Control) 
command 389 
call stack entry message queue 204 
calling procedure 
CALLPRC command description 66 
CALLPRC command example 78 
calling program 
CALL command description 65 
using the CALL command 71 
Callpre (CALL PROCEDURE) 
command 17 
CALLPRC (Call Procedure) 
command 17 
description 66 
example 78 
canceling 
request while testing 373 
CCSID 209 
messages 
using CCSID 201 
CEELOCT program 51 
century digit 
parameter value to CPP (command 
processing program) 
date 289 
change authority 110 
Change Command (CHGCMD) 
command 332 
Change Current Library (CHGCURLIB) 
command 105 
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Change Data Area (CHGDTAARA) 
command. 17, 93 
Change Debug (CHGDBG) 
command 370 
Change Job (CHGJOB) command 266 
Change Library List (CHGLIBL) 
command 24, 105 
Change Message Description 
(CHGMSGD) command 185, 198 
Change Message Queue (CHGMSGQ) 
command 200, 203 
Change Program Variable 
(CHGPGMVAR) command 383 
Change System Library List 
(CHGSYSLIBL) command 105 
Change Variable (CHGVAR) command 
definition 17 
example 27, 213 
changing 
CL program at run time 167 
command 332 
command definition effect on 
program 332 
current library 105 
data area 17,93 
debug 370 
job 266 
library list 24, 105 
message description 185, 198 
message queue 200, 203 
module object 354, 355 
program variable 383 
system library list 105 
variable 
CL procedure 14, 17 
example 27, 213 
variable value 
in program 383 
character 
lowercase 
variable 25 
character length error 77 
Check Object (CHKOBJ) command 17, 
145 
checking 
object 17, 145 
program validity 284 
CHGCMD (Change Command) 
command 332 
CHGCURLIB (Change Current Library) 
command 105 
CHGDBG (Change Debug) 
command 370 
CHGDTAARA (Change Data Area) 
command 17, 93 
CHGJOB (Change Job) command 266 
CHGLIBL (Change Library List) 
command 24, 105 
CHGMSGD (Change Message 
Description) command 185, 198 
CHGMSGQ (Change Message Queue) 
command 200, 203 
CHGPGMVAR (Change Program 
Variable) command 383 
CHGSYSLIBL (Change System Library 
List) command 105 


CHGVAR (Change Variable) command 
%SWITCH setting 46 
CL procedure 14 
definition 17 
example 27, 213 
CHKOBJ (Check Object) command 17, 
145 
choice for parameter 316 
CL command 
Seecommand, CL 
CL procedure 
advantages for using 11 
batch entry 13 
command 
logging 55 
used 17 
compiler listing 56 
controlling processing 21, 30 
creating 
CRTCLMOD command 17 
using CRTCLMOD command _ 13, 
DD 
using source statements 13 
description 2 
example 15 
interactive entry 13 
introduction 11 
obtaining dump 59 
overriding database file 158 
overriding display file 154 
parts 14 
procedure creation 13 
purpose 11 
referring to file 149 
source creation 13 
using 19 
variable, command to work with 17 
working with 55, 143 
working with file 146 
writing comment 29 
CL program 
creating 13 
display formatting 146 
files supported 146 
receiving data 151 
sending data 151 
substring built-in function 
(%SUBSTRING) 
used to process qualified 
name 313 
CL variable 
declaring 14, 17 
Clear Library (CLRLIB) command 113 
Clear Trace Data (CLRTRCDTA) 
command 378, 379 
clearing 
library 113 
trace data 378 
CLRLIB (Clear Library) command 113 
CLRTRCDTA (Clear Trace Data) 
command 378 
CMD (command) parameter 17 
CMD (Command) statement 
defining 287 
example 341 
combined authority 110 


command 
See also command definition 
debug 348 
description 1 
equating aname 367 
STEP debug 361 
command (CMD) parameter 17 
Command (CMD) statement 
defining 287 
example 341 
command analyzer exit points 173 
command default 
changing 333 
command definition 
See command processing program 
(CPP) 
See parameter 
Seecommand processing program 
(CPP) 
data type parameter restriction 293 
defining 
simple list 301 
displaying 331 
effect of changing 332 
example 313 
creating a command to call an 
application program 341 
creating a command to display an 
output queue 342 
creating a command to substitute 
default value 342 
creating abbreviated 
commands 344 
defining a parameter 292 
introduction 4 
mixed list with 306 
object 284 
parameter combination, valid 301 
processing 
qualified name in a CL 
program 313 
prompt text for parameter 288 
required parameter for 288 
return value for parameter 288 
simple list with 301 
source list 328 
statement 
DEP 315 
description 284 
ELEM 306 
error during processing 330 
QUAL 312 
usage 4 
use of qualified name 312 
valid parameter by parameter 
type 301 
Command Entry display 268 
command processing procedure 
writing REXX 339 
command processing program (CPP) 
definition 4 
description 285 
example 342 
writing 337 
command usage 
printing 17 


command, CL 14, 17, 31, 33, 34, 36, 68, 
156, 306, 328 
Add Breakpoint (ADDBKP) 374 
Add Library List Entry 
(ADDLIBLE) 105 
Add Message Description 
(ADDMSGD) 185 
defining substitution 
variables 188 
example 194 
Add Program (ADDPGM) 370 
Add Trace (ADDTRC) 379 
ADDBKP (Add Breakpoint) 374 
ADDLIBLE (Add Library List 
Entry) 105 
ADDMSGD (Add Message 
Description) 
defining substitution 
variables 188 
example 194 
ADDPGM (Add Program) 370 
ADDTRC (Add Trace) 379 
attribute 327 
CALL (Call Program) 65, 71 
Call Procedure (CALLPRC) 66 
Call Program (CALL) 65, 71 
calling 
description 78 
CALLPRC (Call Procedure) 66, 78 
Change Command (CHGCMD) 332 
Change Current Library 
(CHGCURLIB) 105 
Change Data Area 
(CHGDTAARA) 17, 93 
Change Debug (CHGDBG) 370 
Change Job (CHGJOB) 266 
Change Library List (CHGLIBL) 24, 
105 
Change Message Description 
(CHGMSGD) 185, 198 
Change Message Queue 
(CHGMSGQ) 200, 203 
Change Program Variable 
(CHGPGMVAR) 383 
Change System Library List 
(CHGSYSLIBL) 105 
Change Variable (CHGVAR) 14, 27 
changing 332 
changing program control 
command 17 
Check Object (CHKOBJ) 17, 145 
CHGCMD (Change Command) 332 
CHGCURLIB (Change Current 
Library) 105 
CHGDBG (Change Debug) 370 
CHGDTAARA (Change Data 
Area) 17,93 
CHGJOB (Change Job) 266 
CHGLIBL (Change Library List) 24, 
105 
CHGMSGD (Change Message 
Description) 185, 198 
CHGMSGO (Change Message 
Queue) 200, 203 
CHGPGMVAR (Change Program 
Variable) 383 
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CHGSYSLIBL (Change System Library 
List) 105 
CHGVAR (Change Variable) 14, 27 
CHKOBJ (Check Object) 17, 145 
Clear Library (CLRLIB) 113 
Clear Trace Data (CLRTRCDTA) 378, 
379 
CLRLIB (Clear Library) 113 
CLRTRCDTA (Clear Trace Data) 378, 
379 
CMD (Command) statement 288 
command processing program 
(CPP) 285 
Convert Date (CVTDAT) 17, 49 
CREATE BOUND CONTROL 
LANGUAGE (Create Bound CL) 17 
Create Bound Control Language 
(CRTBNDCL) 17 
Create Command (CRTCMD) 284, 
327 
Create Control Language Module 
(CRTCLMOD) 17, 55 
Create Data Area (CRTDTAARA) 17, 
92 
Create Duplicate Object 
(CRTDUPOBJ) 131 
Create Library (CRTLIB) 109 
Create Message File (CRTMSGF) 183, 
184 
Create Message Queue 
(CRTMSGQ) 200 
CREATE PROGRAM 17 
Create Program (CRTPGM) 17 
CREATE SERVICE PROGRAM 17 
Create Service Program 
(CRTSRVPGM) 17 
creating 
definition 284 
process 327 
steps 283 
CRTCLMOD (Create Control 
Language Module) 17, 55 
CRTICMD (Create Command) 284, 
327 
CRIDTAARA (Create Data Area) 17, 
92 
CRTDUPOBJ (Create Duplicate 
Object) 131 
CRTLIB (Create Library) 109 
CRTMSGF (Create Message File) 183, 
184 
CRTMSGQ (Create Message 
Queue) 200 
CVTDAT (Convert Date) 17, 49 
DCL (Declare CL Variable) 14, 17 
DCLF (Declare File) 
description 14 
using 150 
variables 22 
Deallocate Object (DLCOBJ) 139 
Declare CL Variable (DCL) 14, 17 
Declare File (DCLF) 
description 14 
using 150 
variables 22 
defined, authority needed 286 
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defining 
dependent relationship 315 
description 283 
error encountered 330 
example 341 
instructions 287 
list within list 308 
mixed list 306 
qualified name 312 
source list 328 
validity checking 339 
Delete Command (DLTMCD) 328 
Delete Data Area (DLTDTAARA) 17 
Delete File (DLTF) 14 
Delete Library (DLTLIB) 113 
Delete Program (DLTPGM) 17 
Display Breakpoints (DSPBKP) 382 
Display Command (DSPCMD) 331 
Display Data Area 
(DSPDTAARA) 17, 93 
Display Debug (DSPDBG) 382 
Display Job (DSPJOB) 141 
Display Job Log (DSPJOBLOG) 272 
Display Library (DSPLIB) 114 
Display Library Description 
(DSPLIBD) 115 
Display Log (DSPLOG) 276 
Display Message Descriptions 
(DSPMSGD) 185, 194 
Display Messages (DSPMSG) 200 
Display Object Description (DSPOBJD) 
common attributes 97 
log-version selection 276 
use 117 
Display Program Variable 
(DSPPGMVAR) 382 
Display Spooled File (DSPSPLF) 272 
Display Trace (DSPTRC) 382 
Display Trace Data 
(DSPTRCDTA) 379, 381 
displaying 331 
DLCOBJ (Deallocate Object) 139 
DLTCMD (Delete Command) 328 
DLTDTAARA (Delete Data Area) 17 
DLTF (Delete File) 14 
DLTLIB (Delete Library) 113 
DLTPGM (Delete Program) 17 
DSPBKP (Display Breakpoints) 382 
DSPCMD (Display Command) 331 
DSPDBG (Display Debug) 382 
DSPDTAARA (Display Data 
Area) 17,93 
DSPJOB (Display Job) 141 
DSPJOBLOG (Display Job Log) 272 
DSPLIB (Display Library) 114 
DSPLIBD (Display Library 
Description) 115 
DSPLOG (Display Log) 276 
DSPMSG (Display Messages) 200 
DSPMSGD (Display Message 
Descriptions) 185, 194 
DSPOBJD (Display Object Description) 
common attributes 97 
log-version selection 276 
use 117 
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DSPPGMVAR (Display Program 
Variable) 382 
DSPSPLF (Display Spooled File) 272 
DSPTRC (Display Trace) 382 
DSPTRCDTA (Display Trace 
Data) 379, 381 
effect of changing definition 332 
End Do (ENDDO) 17, 33 
End Program (ENDPGM) 14, 17 
End Receive (ENDRCV) 156, 157, 
158 
End Request (ENDRQS) 373 
ENDDO (End Do) 17, 33 
ENDPGM (End Program) 14, 17 
ENDRCV (End Receive) 156, 157, 
158 
ENDROQOS (End Request) 373 
example of creating 341 
frequently used in CL procedure 17 
functions 17 
GOTO (Go To) 17, 31 
Load and Run Media Program 
(LODRUN) 179 
LODRUN (Load and Run Media 
Program) 179 
logging CL procedure 55 
Merge Message File 
(MRGMSGF) 183, 185 
Monitor Message (MONMSG) 46, 
235 
MONMSG (Monitor Message) 46, 
235 
Move Object (MOVOBJ) 129 
MOVOBJ (Move Object) 129 
MRGMSGEF (Merge Message 
File) 183, 185 
online help information, 
providing 285 
Override with Database File 
(OVRDBF) 14 
Override with Message File 
(OVRMSGF) 195 
OVRDBF (Override with Database 
File) 14 
OVRMSGF (Override with Message 
File) 195 
Print Command Usage 
(PRTCMDUSG) 17 
processing program (CPP) 
definition 4 
writing 337 
PRTCMDUSG (Print Command 
Usage) 17 
RCLRSC (Reclaim Resources) 372 
RCVF (Receive File) 148, 157 
RCVMSG (Receive Message) 228, 229 
Receive File (RCVF) 148, 157 
Receive Message (RCVMSG) 228, 229 
Reclaim Resources (RCLRSC) 372 
Remove Breakpoint (RMVBKP) 378 
Remove Library List Entry 
(RMVLIBLE) 105 
Remove Message (RMVMSG) 17, 234 
Remove Message Description 
(RMVMSGD) 185 
Remove Program (RMVPGM) 370 
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Rename Object (RNMOBJ) 133 

Resume Breakpoint (RSMBKP) 375 

Retrieve Configuration Source 
(RTVCFGSRC) 17, 51 

Retrieve Configuration Status 
(RTVCFGSTS) 17, 51 

Retrieve Data Area 
(RTVDTAARA) 17, 93 

Retrieve Job Attributes 
(RTVJOBA) 17, 52 

Retrieve Library Description 
(RTVLIBD) 115 

Retrieve Member Description 
(RTVMBRD)_ 17, 54 

Retrieve Message (RTVMSG) 17, 233 

Retrieve Network Attributes 
(RTVNETA) 51 

Retrieve Object Description 
(RTVOBJD) 53, 121 

Retrieve System Value 
(RTVSYSVAL) 17, 48 

Retrieve User Profile 
(RTVUSRPRF) 17, 53 

RMVBKP (Remove Breakpoint) 378 

RMVLIBLE (Remove Library List 
Entry) 105 

RMVMSG (Remove Message) 17, 234 

RMVMSGD (Remove Message 
Description) 185 

RMVPGM (Remove Program) 370 

RNMOBJ (Rename Object) 133 

RSMBKP (Resume Breakpoint) 375 

RTVCFGSRC (Retrieve Configuration 
Source) 17, 51 

RTIVCFGSTS (Retrieve Configuration 
Status) 17,51 

RTVDTAARA (Retrieve Data 
Area) 17,93 

RTIVJOBA (Retrieve Job 
Attributes) 17, 52 

RIVLIBD (Retrieve Library 
Description) 115 

RTVMBRD (Retrieve Member 
Description) 17, 54 

RTVMSG (Retrieve Message) 17, 233 

RTVNETA (Retrieve Network 
Attributes) 51 

RTVOBJD (Retrieve Object 
Description) 53, 121 

RTVSYSVAL (Retrieve System 
Value) 17, 48 

RTVUSRPREF (Retrieve User 
Profile) 17, 53 

selective prompting 168 

Send Break Message 
(SNDBRKMSG) 207 

Send File (SNDF) 148, 157 

Send Message (GSNDMSG) 207 

Send Program Message 
(SNDPGMMSG) | 14, 208 

Send Reply (GNDRPY) 17, 234 

Send User Message 
(SNDUSRMSG) | 17, 209 

Send/Receive File (SNDRCVF) 148, 
151 


command, CL (continued) 
setting CL procedure limits 
command 17 
SNDBRKMSG (Send Break 
Message) 207 
SNDF (Send File) 148, 157 
SNDMSG (Send Message) 207 
SNDPGMMSG (Send Program 
Message) 14, 208 
call stack entry 214 
SNDRCVF (Send/Receive File) 148, 
151 
SNDRPY (Send Reply) 17, 234 
SNDUSRMSG (Send User 
Message) 17, 209 
specifying prompt override program 
when changing 324 
when creating 324 
Start Debug (STRDBG) 370, 378 
Start Programmer Menu 
(STRPGMMNU) 172 
STRDBG (Start Debug) 370, 378 
STRPGMMNU (Start Programmer 
Menu) 172 
TFRCTL (Transfer Control) 389, 390 
Transfer Control (TFRCTL) 389, 390 
used frequently in CL procedure 17 
used in CL procedure 17 
using the prompter 168 
Work with Object Locks 
(WRKOBJLCK) 141 
WRKOBJLCK (Work with Object 
Locks) 141 
command, Display Audit Journal Entries 
DSPAUDJRNE 111 
comment delimiter (/*) 30 
communicate 
between procedure 89 
using data area 89 
compiler error 58 
compiler listing 
CL procedure 56 
sample program 57 
compiler, CL 
installing support for 63 
compiling 
source programs 62 
completion message 183, 210 
compressing 
object 135 
object table 135 
conditional breakpoint 
adding 377 
example 360 
removing 358 
setting 358 
conditional processing of command 30 
conditional prompting 317 
configuration source 
retrieving 17,51 
configuration status 
retrieving 17,51 
constant value 
defining for parameter 288 
control 
transferring 
description 389 


control (continued) 
transferring (continued) 
use 390 
control language (CL) 
See alsocommand, CL 
command 
definition 1 
entering 1 
syntax 2 
menu 
using CL program to control 152 
procedure 
creating 17, 55 
description 2 
monitoring for message 235 
parts 14 
referring to object 143 
used within CL 2 
program 
allowing user changes at run 
time 167 
controlling flow between 
programs 65 
controlling menu 152 
controlling processing 21 
DBCS data 174 
description 11 
display file, using 147 
display formatting 146 
example 15 
example program 175 
files supported 146 
introduction 11 
message handling 203 
message subfile 166 
receiving data 151 
receiving message 228 
sending data 151 
sending message 208 
substring built-in function 
(%SUBSTRING) 313 
control processing with CL command 21 
controlling 
logic flow in CL procedure 30 
processing in CL procedure 30 
Convert Date (CVTDAT) command 17, 
49 
converting 
date 17,49 
date format 49 
CPP (command processing program) 
definition 4 
description 285 
example 341 
writing 337 
create 
creating 17 
Create Bound Control Language 
(CRTBNDCL) command 17 
Create Command (CRTCMD) command 
CL program 283 
example 341 
parameters 327 
processing 284 
relationship 338 
Create Control Language Module 
(CRTCLMOD) command 17, 55 


Create Data Area (CRTDTAARA) 
command 17,92 
Create Duplicate Object (CRTDUPOB]J) 
command 131 
Create Library (CRTLIB) command 109 
Create Message File (CRTMSGF) 
command 183, 184 
Create Message Queue (CRTMSGQ) 
command 200 
Create Program (CRTPGM) 
command 17 
Create Service Program (CRTSRVPGM) 
command 17 
creating 
CL procedure 17,55 
command 
attribute 327 
description 284, 327 
example 286, 341 
create 17 
data area 17, 92 
duplicate object 131 
information for object 123 
library 109 
message file 183, 184 
message queue 200 
online help information 285 
valid type 92 
CRTBNDCL (Create Bound Control 
Language) command 17 
CRTICLMOD (Create Control Language 
Module) command 17,55 
CRTCMD (Create Command) command 
CL program 283 
example 341 
parameters 327 
processing 284 
relationship 338 
CRIDTAARA (Create Data Area) 
command 17,92 
CRTDUPOBJ (Create Duplicate Object) 
command 131 
CRTLIB (Create Library) command 109 
CRTMSGF (Create Message File) 
command 183, 184 
CRTMSGO (Create Message Queue) 
command 200 
CRTPGM (Create Program) 
command 17 
CRTSRVPGM (Create Service Program) 
command 17 
current library 
changing 105 
CVTDAT (Convert Date) command 17, 
49 


D 


data area 92 
changing 17,93 
communicate 89 
creating 17, 92 
deleting 17 
description 89 
displaying 17, 93 
example of retrieving 93 
group 90 
453 
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data area (continued) 
initial value 89 
retrieving 17,93 
data area, command to work with 17 
data authority 110 
data queue 
allocating 83 
communicating between 
programs 78 
creating 83 
example 84 
managing storage 83 
sending data 83 
using 84 
data type error 74 
database file 158 
overriding 14 
receiving data area 158 
referring to output file 159 
using as data queue 82 
date 
conversion 17 
converting format 49 
DBCS (double-byte character set) 
defining message 194 
designing application program 174 
sending message 192 
using QCMDEXC with 164 
writing CL program with DBCS 
data 174 
DCL (Declare CL Variable) 
command 14, 17 
DCLF (Declare File) command 
CL procedure 14, 17 
declaring 
variable 150 
description 22 
Deallocate Object (DLCOBJ) 
command 139 
deallocating 
object 139 
debug 
changing 370 
command 348 
displaying 382 
session 
adding program object 351 
prepare program object 349 
removing program object 352 
starting 378 
debug command 
BREAK 359 
CLEAR 359 
debugger 
ILE source 347 
debugging 369 
batch job not started from job 
queue 385 
batch job submitted to a job 
queue 384 
considerations for one job from 
another job 386 
from another job 384 
ILE program 347 
ILE source debugger commands 350 
interactive job 386 
machine interface level 387 
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debugging (continued) 
running job 385 
starting 370 
starting ILE source debugger 350 
testing applications 369 
decimal length error 76 
Declare CL Variable (DCL) 
command 14, 17 
Declare File (DCLF) command 
CL procedure 14, 17 
declaring 
variable 24, 150 
description 22 
declaring 
CL variable 14 
decompressing 
object 135 
default delivery of message 201 
default handling 240 
unmonitored message while 
testing 372 
unmonitored, default handling 372 
default program 
used in testing 370 
default value 
changing command 333 
defining for parameter 292 
message 192 
reply 192 
default value table 292 
defining 
CL command table 284 
command 
authority 286 
definition 283 
parameter 316 
statements 287 
element in list 
simple list 302 
list for parameter 301 
list within list 308 
optional parameter 288 
parameter 288 
prompt text fora parameter 288 
qualified name 312 
required parameter 288 
restricted value for parameter 288 
return value for parameter 288 
simple list 302 
substitution variable 188 
valid parameter 288 
definition object, command 284 
definition statement, command 284 
delete authority 110 
Delete Command (DLTCMD) 
command 328 
Delete Data Area (DLTDTAARA) 
command 17 
Delete File (DLTF) command 14 
Delete Library (DLTLIB) command 113 
Delete Program (DLTPGM) 
command 17 
deleting 
command 328 
data area 17 
file 14 
file member 345 


deleting (continued) 
HLL programs 345 
library 113 
object 137 
program 17 
program object 345 
QHST file 281 
source member 345 
DEP (Dependent) statement 
command definition 287 
example 315 
use 315 
detailed message 
description 268 
detecting unused object on system 123 
diagnostic message 183, 210 
display 376 
breakpoint 376 
Command Entry 13 
menu, using for command entry 13 
programmer menu 16, 172 
trace data 379 
unmonitored message 
breakpoint 372 
Display Audit Journal Entries 
(DSPAUDJRNE) command 111 
Display Breakpoints (DSPBKP) 
command 382 
Display Call Stack display 232 
Display Command (DSPCMD) 
command 331 
Display Data Area (DSPDTAARA) 
command 17, 93 
Display Debug (DSPDBG) 
command 382 
display file 
creating 150 
receiving 148, 151 
referring to 149 
sending 151 
using in CL program 147 
using multiple device displays 155 
Display History Log Contents 
display 276 
Display Job (DSPJOB) command 141 
Display Job Log (DSPJOBLOG) 
command 272 
Display Library (DSPLIB) command 114 
Display Library Description (DSPLIBD) 
command 115 
Display Log (DSPLOG) command 276 
Display Message Descriptions 
(DSPMSGD) command 185, 194 
Display Messages (DSPMSG) 
command 200 
Display Object Description (DSPOBJD) 
command 
description 97 
log-version selection 276 
use 117 
Display Program Variable (DSPPGMVAR) 
command 382 
Display Spooled File (DSPSPLF) 
command 272 
Display Trace (DSPTRC) command 382 
Display Trace Data (DSPTRCDTA) 
command 379, 381 


displaying 275 
batch job log 276 
breakpoint 382 
command 331 
command definition 331 
data area 17,93 
debug information 382 
history log (QHST) 276 
job 141 
job log 272 
library 114 
library description 115 
log 276 
message 200, 343 
message description 185, 194 
module attribute 60 
object description 
common attributes 97 
log-version selection 276 
use 117 
object in library 114 
object lock 141 
program attribute 60 
program variable 382 
QHST log 276 
spooled file 272 
testing information 382 
trace 382 
trace data 379, 381 
value of variable in a program 382 
DLCOBJ (Deallocate Object) 
command 139 
DLTCMD (Delete Command) 
command 328 
DLTDTAARA (Delete Data Area) 
command 17 
DLTF (Delete File) command 14 
DLTLIB (Delete Library) command 113 
DLTPGM (Delete Program) 
command 17 
DO (Do) command 17, 33 
DO group 33 
documentation aid 
listing CL command 56 
double-byte character set (DBCS) 
defining message 194 
designing application program 174 
sending message 192 
using QCMDEXC with 164 
writing CL program with DBCS 
data 174 
double-byte data 
defining double-byte message 194 
designing application program 174 
how to send immediate 192 
prompting for in CL program 164 
prompting for using QCMDEXC 
program 164 
sending message that contains 
double-byte characters 192 
using in CL program 174 
double-byte message 194 
DSPAUDJRNE 111 
DSPBKP (Display Breakpoints) 
command 382 
DSPCMD (Display Command) 
command 331 


DSPDBG (Display Debug) 
command 382 
DSPDTAARA (Display Data Area) 
command 17, 93 
DSPJOB (Display Job) command 141 
DSPJOBLOG (Display Job Log) 
command 272 
DSPLIB (Display Library) command 114 
DSPLIBD (Display Library Description) 
command 115 
DSPLOG (Display Log) command 276 
DSPMSG (Display Messages) 
command 200 
DSPMSGD (Display Message 
Descriptions) command 185, 194 
DSPOBJD (Display Object Description) 
command 
description 97 
log-version selection 276 
use 117 
DSPPGMVAR (Display Program Variable) 
command 382 
DSPSPLF (Display Spooled File) 
command 272 
DSPTRC (Display Trace) command 382 
DSPTRCDTA (Display Trace Data) 
command 379, 381 
duplicate object 
creating 131 


E 


element 
defining in a list 306 
Element (ELEM) statement 
command definition 287 
example 306, 309 
use 306 
ELSE (Else) command _ 17, 34 
embedded IF (If) command 36 
End Do (ENDDO) command _ 17, 33 
End Program (ENDPGM) command 
CL procedure 14, 17 
example 167 
End Receive (ENDRCV) command 
multiple device display files 156, 
157, 158 
End Request (ENDRQS) command 373 
end, abnormal 177 
ENDDO (End Do) command 17, 33 
ending 
program 14,17 
receive 156, 157, 158 
request 373 
ENDPGM (End Program) command 
CL procedure 14, 17 
example 167 
ENDRCV (End Receive) command 
multiple device display files 156, 
157, 158 
ENDROQS (End Request) command 373 
entry 
batch 13 
interactive 13 
error 
calling program 74 
character length 77 


error (continued) 
command definition statement 330 
compiler 58 
data type 74 
decimal length 76 
precision 76 
procedure 74 
escape message 
CPF2469 196 
definition 183 
monitoring 235 
sending 211 
example 
*BCAT value 212 
adding 
breakpoint to program 375 
trace to program 378 
ADDMSGD (Add Message 
Description) command 194 
attribute of variable 367 
BIN function 41 
binary function 41 
break-handling program 243 
CALL command 65 
CALLPRC command 66 
change variable 
character 366 


decimal 367 
logical 366 
changing 


lock state 140 
message 211 
variable value 27 
CL procedure 
control processing 21 
simple 15 
typical 13, 19 
CL program 
processing qualified name 313 
command processing program 342 
compiler listing 57 
conditional breakpoint 360 
controlling menu 152 
converting system value 49 
creating 
CL procedure 16 
command 286, 341, 342 
command to call application 
program 341 
command to display output 
queue 342 
command to substitute default 
value 342 
creating abbreviated 
commands 344 
CRTMSGEF (Create Message File) 
command 184 
data queue 84 
DBCS data in CL programs 174 
DDS 
display file 150 
declaring display file 150 
defining 
parameter 293, 341 
prompt text for command 
name 341 
deleting QHST file 281 
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example (continued) exclusive allow read (*EXCLRD) lock file (continued) 


describing state 138 declaring 
message 194 execute authority 110 in CL program 150 

display character variable 364 expression name 22 
display decimal variable 365 equating aname 367 to program 17 
display file 150 logical 37 variable 14 
display logical variable 364 relational 37 deleting 14, 344 
displaying variables in hexadecimal display 

format 365 closing 149 
DO command 33 F declaring 149 

QMHCID 397 


IF (If) command 31 
initial program 106 
logging message in job log 268 


using as parameter value 288 
receiving 
data 148, 157 


MHCRP 399 
MHCSP 399 


logical expression 37 MOTE i record 17,151 
message 194 MHJDT 394, 400 sending 
message handling program 203 MHJOB 399 CL procedure 17 
monitorin data 148, 157 
messa. : f ifi a a bfil ds 151 
ge for specific MHJTS 400 subfile records 
command a7 MHLIN 401 file member 
message within procedures 239 MHLNN 401 deleting 345 
ae a — : MHLSP 400 — so aes 
= MMT 3 — 
qualified name 6 NE ee using severity code filter (SEV) 
Sa : MHMID 395 
overriding message file 197 MHMKS 401 parameter 201 
aah . - MHMRK 394 format of in ie 
control to procedure MHMSC_ 400 converting 


control to program 65 
parameter 74 


frequently-used objects 
description 137 


&s5 
Pe 
G2 
wSS 
oN 


processing function 
qualified name in CL CL commands 17 
program 313 seis ae testing 
prompt override program 324 MHRPY 395 description 8 


QINSTAPP program 179 


qualified name of object 6 ed — G 
receiving message from 
MHRTM 399 
ee ee MHRTY 396 general purpose library (QGPL) 114 
Teplaeng: Hisnany ak 108 MHSEV 395 generic name 
Te, Aes MHSID 401 description 107 
‘ob attribute 52 MHSLB 398 Get Current Local Time (CEELOCT) 51 
a MHSMD_ 397 GOTO (Go To) command 17, 31 
network attribute 52 
bject description 123 Me ae 
. ie ia = pe MHSPR 397 
i nan i MHSSN 396 | 
user profile 54 MHSTM 398 
runtime call stack 216, 226 MHSTY 396 handling 
sample CL program 175 MHSYN 401 default 240 
sample default message program 193 MHSYS 399 help information 
saving library list 106 MHTID 400 Seeonline help information 
sending help panel group 
MHTIM 395 ; : : 
message 211 online help information 285 
MHTTY 401 : 
program message 210 MHTYP 394 high-level language (HLL) program 165 
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mixed list 307 
QCMDEXC program 161 
history log (QHST) 
description 275 
format 278 
format table 278 
version 275 
HLL (high-level language) program 
mixed list 307 
QCMDEXC program 161 
hold delivery of message 201 


SST function 43 

substring function 43 

switch function 45 

TOPGMQ(*PRV*) 217 

Transfer Control (TFRTCL) 

command 390 

using *CTLBDY 227 

using *PGMBDY 222, 223, 224 

using complex name 220 

using simple name 219 
exception message 

using the RMV keyword 229 
exclusive (EXCL) lock state 138 


file 
See also object 
See alsomember 
CL procedure 
overriding database file 158 
overriding display file 154 
referring to 149 
working with 146 
database 
closing 149 
declaring 149 
opening 149 
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If (IF) command 
CL procedure 17 
IF (If) command 17 
description 17 
embedded 36 
example 31 
using %SWITCH with 45 
ILE (Integrated Language Environment) 
model 
CL program 
debugging 347 
message queue 
call stack entry 204 
notify message 211 


procedure 
receiving 271 
sending 271 


source debugger 347 
starting source debugger 350 
immediate message 181 
impromptu message 
Seemessage, immediate 
informational message 181, 209 
initializing 
library list 105 
input field length 292 
inquiry message 181, 209 
installing 
CL compiler support 63 
instruction, stepping 381 
Integrated Language Environment (ILE) 
model 
message queue 
call stack entry 204 
notify message 211 
procedure 
receiving 271 
sending 271 
Integrated Language Environment (ILE) 
procedure 
call stack entry message queue 204 
receiving 271 
sending 271 
interactive 
entry 13 
job 
debugging another 386 
job log 
consideration 274 


J 
job 
batch 
testing functions 369 
changing 266 
displaying 141 
interactive 
testing functions 369 
submitting 177 
job attribute 
retrieving 17,52 
job log 
consideration for interactive 274 
description 266 


job log (continued) 


directing 393 

displaying 272 

model for primary 393 
output file 393 

preventing production of 273 
suggestions when using 273 


job message queue 200, 203 
job queue 


debugging batch job not started 
from 385 

debugging batch job submitted 
to 384 


K 


key parameter 
defining 288 
identifying 321 
using 320 


L 


label 
in CL procedure 31 
language 
feature code 115 
using different 115 
LDA (local data area) 90 
length of parameter value table 292 
library 
allocating resource 138 
authority 109 
clearing 113 
creating 109 
definition 5 
deleting 113 
description 98 
displaying 
library list 107 
names and contents 114 
object 114 
object description 117 
grouping 6 
grouping object 108 
placing object in 113 
previous-release 62 
production 109 
renaming consideration 133 
retrieving object description 53, 121 
security 109 
test 109 
library description 
displaying 115 
retrieving 115 
library list 
*CURLIB value 99 
accessing object 100 
changing 24, 105 
comparison with qualified name 102 
current library 99, 104 
displaying 107 
entry 
adding 105 
removing 105 


library list (continued) 
initializing 
QSYSLIBL system value 105 
QUSRLIBL system value 105 
job 104 
part of 
current library 99 
product library 99 
system part description 99 
user part 99 
product library 104 
saving 106 
search order 100 
setting up 106 
system part 104 
user part 104 
library name 
specifying 98 
list 
CL or HLL for list within 309 
CL or HLL for mixed 307 
CL or HLL for simple 303 
command definition 328 
defining 301 
REXX 
mixed 308 
simple 305 
within 311 
variable to specify 24 
list of parameter value 
defining 301 
elements 
using Element (ELEM) 
statement 306 
simple 301 
list within list 308 
using CL or HLL for 309 
using REXX for 311 
listing view 
using 350 
Load and Run Media Program 
(LODRUN) command 179 
local data area 90 
lock state 
*EXCL (exclusive) 138 
*EXCLRD (exclusive allow read) 138 
*SHRNUP (shared-no-update) 138 
*SHRRD (shared-for-read) 138 
*SHRUPD (shared-for-update) 138 
combination table 138 
exclusive (*EXCL) 138 
exclusive allow read (*EXCLRD) 138 
object type table 138 
shared-for-read (*SHRRD) 138 
shared-for-update (“SHRUPD) 138 
shared-no-update (*SHRNUP) 138 
log 
consideration for batch job 275 
displaying 276 
displaying system 275 
history 275 
job 266 
QHST (history) 275 
logging CL procedure command 55 
logic control command 14 
logical expression 37 
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member 
source 
deleting 344 
member description 
retrieving 17, 54 
menu 
introduction 4 
programmer 172 
Merge Message File (MRGMSGF) 
command 183, 185 
merging 
message file 183, 185 
message 199, 275 
adding to file 185 
assigning message identifier 185 
assigning severity code 187 
break delivery 200 
break-handling program 203 
changing delivery mode 203 
completion 183 
default handling while testing 373 
default value 192 
defining 
description 186 
help 186 
substitution variable 188 
definition 7 
delivery 200 
describing predefined 185 
description 
definition 8 
diagnostic 183 
displaying 
break delivery 200 
command options 181 
double-byte 
defining 194 
escape 
definition 183 
description 235 
purpose 210 
example 
changing 211 
sending 211 
file 
IBM-supplied 181 
filtering 
description 267 
handling 181 
IBM-supplied message file 181 
immediate 7, 181 
informational 181, 209 
inquiry 181, 209 
job message queue 203 
logging in history log 266 
logging on job log 266 
monitoring 
description 235 
example 17 
numeric subtype code 186 
use 46 
notify 183, 241 
online help information 186 
overriding message file 195 
parameters 46 
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message (continued) 

predefined 

description 7 

IBM-supplied file 181 

message queue 181 
QHST (history log) file 279 
queue 8 
receiving 

CL procedure 17, 228 

CL program 228 
removing 

CL procedure 17 

from message queue 234 
reply 183 
request 183, 230 
retrieving 

CL procedure 17 

from CL procedure 233 

in CL procedure 233 
sample program to receive from 

QSYSMSG 261 

sending 181, 207 
sending from CL program 208 
sending to system user 207 
sent to QSYSMSG message queue 

CPD4070 245 

CPF0907 245 

CPF1269 246 

CPF1393 246 

CPF1397 246 

CPF510E 246 

CPF5167 247 

CPF5244 247 

CPF5248 247 

CPF5250 247 

CPF5251 247 

CPF5257 248 

CPF5260 248 

CPF5274 248 

CPF5341 248 

CPF5342 248 

CPF5344 249 

CPF5346 249 

CPF5355 249 

CPF8AC4 245 

CPF9E7C 245 

CPIO91F 249 

CPI0948 249 

CPI0949 250 

CPI0950 250 

CPI0953 250 

CPI0954 250 

CPI0955 250 

CPI0964 250 

CPI0965 250 

CPI0966 250 

CPI0970 250 

CPI0988 250 

CPI0989 251 

CPI0998 251 

CPI0999 251 

CPI099C 251 

CPI099D = 252 

CPIO99E 252 

CPIO99F 253 

CPI117 251 

CPI1136 254 


message (continued) 
sent to QSYSMSG message queue 
(continued) 

CPI1138 254 
CPI1139 254 
CPI1153 254 
CPI1154 254 
CPI1159 254 
CPI1160 255 
CPI1161 255 
CPI1162 255 
CPI1165 255 
CPI1166 255 
CPI1167 255 
CPI1168 255 
CPI1169 255 
CPI116A 253 
CPI116B 253 
CPI116C 253 
CPI1171 255 
CPI1468 256 
CPI2239 256 
CPI2283 256 
CPI2284 256 
CPR2AA 256 
CPI8898 257 
CPI8A13 256 
CPI8A14 256 
CPI9014 257 
CPI9490 257 
CPI94A0 257 
CPI94CE 257 
CPI94CF 257 
CPI94FC = 257 
CPI96CO 257 
CPI96C1 257 
CPI96C2 258 
CPI96C3 258 
CPI96C4 258 
CPI96C5 = 258 
CPI96C6 = 258 
CPI96C7 258 
CPPODD9 257 
CPPODDA 258 
CPPODDB 258 
CPPODDC 258 
CPPODDD 258 
CPPODDE 259 
CPPODDF 259 
CPP29B0 259 
CPP29B8 259 
CPP29B9 259 
CPP29BA 259 
CPP951B 259 
CPP9522 259 
CPP955E 259 
CPP9575 259 
CPP9576 260 
CPP9589 260 
CPP9616 260 
CPP9617 260 
CPP9618 260 
CPP961F 260 
CPP9620 260 
CPP9621 260 
CPP9622 260 
CPP9623 260 


message (continued) 
sent to QSYSMSG message queue 
(continued) 
CPP962B 261 
size of message file 184 
status 
definition 183 
description 241 
using 211 
subfile 
using 166 
text 186 
type 181 
using system reply list 263 
validity checking 190 
working with 181, 207 
message description 
adding 181 
example 194 
substitution variable 188 
toa file 185 
value 181 
changing 181, 185, 198 
definition 7 
displaying 185, 194 
removing 181, 185 
working with 181 
message file 
changing 181 
creating 181, 183, 184 
merging 183, 185 
overriding with 195 
specifying entry size 184 
specifying maximum size 183 
message files in independent ASPs 184 
message help 186 
message identifier 
specifying 186 
message logging levels 
detailed 268 
high-level 268 
message queue 
amount of storage 200 
call stack entry 204 
changing 200, 203 
creating 181, 200 
QSYSMSG 245 
QSYSOPR 202 
sending message from program 
to 208 
sending message to 207 
work station 202 
working with 181 
message queue type table 209 
message reference key 228 
message subfile 166 
message type table 209 
message, immediate 7 
mixed list 
defining 306 
description 306 
element in list 
mixed list 306 
passing to CPP 306 
using CL or HLL for 307 
using REXX for 308 
model for primary job log 393 


module 
description 1 
module attribute 
displaying 60 
module object 
changing view 354, 355 
Monitor Message (MONMSG) command 
in CL procedure 235 
use 46 
monitoring 
message 
in CL procedure 235 
program level 237 
specific command level 237 
use 46 
MONMSG (Monitor Message) command 
in CL procedure 235 
use 46 
Move Object (MOVOBJ) command 129 
moving 
object from one library to 
another 129 
MOVOB] (Move Object) command 129 
MRGMSGF (Merge Message File) 
command 183, 185 


N 


National Language Sort Sequence 
(NLSS) 359 
national language support 115 
National Language Support 368 
national language version 
definition 115 
nested Do group 
example 33 
nesting 
description 371 
network attribute 
retrieving 51 
notify delivery of message 200 
notify message 
defining 183 
monitoring 236, 241 
sending 211 
number of 
number of statement ranges for 379 
programs that can be debugged 
simultaneously 370 
statement ranges for trace 379 
values in list 288 
numeric parameter value 
replacing 26 
variable replacing 17 


O 


object 
accessing 
with library list 99 
with qualified name 98 
allocating 138 
authority verification 97 
checking 17, 145 
CL procedure 
working with 143 
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command definition 284 
common attribute 97 
common function table 98 
compressing 
restriction 135 
table 135 
use 135 
creating 131 
information 123 
providing description 117 
using variable 22 
damage detection and notification 97 
deallocating 139 
decompressing 
after operating system 
installation 136 
restrictions 135 
temporarily 136 
default auditing attribute 113 
default public authority 111 
definition 4 
deleting 137 
describing 117 
description 97 
detecting unused 123 
displaying in library 114 
duplicate 131 
function performed on 97, 98 
generic name 107 
grouping 6 
library 98 
lock enforcement 97 
lock state 138 
module 
changing 354 
changing view 355 
moving 
restriction 130 
moving between libraries 129 
moving from test library to 
production 176 
naming 5 
placing in library 113 
program 
adding to debug session 351 
prepare for debug session 349 
removing from debug session 352 
qualified name 
description 6 
example 6 
referring to 
in CL procedure 143 
object 143 
renaming 133 
renaming object 
restriction 133 
restriction 
duplicating 132 
saving specific 176 
searching for multiple 108 
searching for single 108 
security 109, 111 
specific functions 98 
TEXT (text) parameter 117 
type 97 
updating 124 
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object (continued) 
type verification 97 
types 5 
usage information 124 
object authority 109 
object description 
displaying 
log-versions 276 
online help 97 
use 117 
retrieving 53, 121 
object existence (*OBJEXIST) 
authority 109 
object lock 
working with 141 
object management (*OBJMGT) 
authority 109 
object operational (“OBJOPR) 
authority 109 
obtaining 
program dump 59 
online help information 
command 285 
help panel group for 285 
providing for command 285 
operator 
arithmetic 37 
character 37 
logical 37 
relational 37 
OPM (original program model) 
sending or receiving 271 
OPM (original program model) program 
message queue 
call stack entry 204 
optional parameter 
defining 288 
original program model (OPM) 
sending or receiving 271 
original program model (OPM) program 
message queue 
call stack entry 204 
OS/400 language support 115 
Override with Database File (OVRDBF) 
command 14 
Override with Message File (OVRMSGF) 
command 195 
overriding 
database file 14 
message file 195 
OVRDBF (Override with Database File) 
command 14 
OVRMSGEF (Override with Message File) 
command 195 


P 


parameter 

See alsocommand definition 

CMD (command) 17 

defining 288 
consideration 288 
constant value 288 
default value 292 
description 288 
determining valid value 288 
example 293 
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parameter (continued) 


defining 288 (continued) 
keyword, naming 289 
optional 288 
passing attribute information 288 
required 288 
restricted value 288 
return value 288 
type 289 
using qualified name 312 
valid by parameter type 301 
valid combination 301 
valid value 288 
value length 292 
with list within list 308 
with mixed list 306 
with simple list 301 
EXITPGM (exit program) 173 
identifying key 321 
key 320 
order of 68 
passing 72, 390 
passing attribute information 288 
passing between programs 68 
possible choice and value 316 
receiving 72 
restricted value for parameter 288 
RQSDTA (request data) 17 
RTNCDE (return code) 37 
specifying 
length returned with value 288 
prompt text 288 
value length 288 
TEXT (text) 117 
trailing blanks 28 
type 
character (*CHAR) 289 
decimal (*DEC) 289 
generic name (*“GENERIC) 289 
integer (*“INTn) 289 
logical (*LGL) 289 
name (*NAME) 289 
null (*“NULL) 289 
path name (*PNAME) 289 
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